使用適用於 DynamoDB 的 Rust 用戶端加密程式庫

本主題說明 DynamoDB 的 Rust 用戶端加密程式庫 1.x 版中的一些函數和協助程式類別。

如需使用 DynamoDB 的 Rust 用戶端加密程式庫進行程式設計的詳細資訊，請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 Rust 範例。

項目加密程式

DynamoDB 的 AWS Database Encryption SDK 本身是項目加密程式。您可以使用適用於 DynamoDB 的 Rust 用戶端加密程式庫 1.x 版，以下列方式加密、簽署、驗證和解密 DynamoDB 資料表項目。

適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK

您可以使用資料表加密組態來建構 DynamoDB 用戶端，該用戶端會自動加密和簽署具有 DynamoDB PutItem請求的用戶端項目。

您必須使用 DynamoDB API 的低階 AWS 資料庫加密 SDK，才能使用可搜尋的加密。

如需示範如何使用 DynamoDB API 的低階 AWS 資料庫加密 SDK 的範例，請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 basic_get_put_example.rs。

較低層級 DynamoDbItemEncryptor

較低層級會DynamoDbItemEncryptor直接加密和簽署或解密，並驗證您的資料表項目，而無需呼叫 DynamoDB。它不會發出 DynamoDB PutItem或 GetItem 請求。例如，您可以使用較低層級DynamoDbItemEncryptor直接解密和驗證您已擷取的 DynamoDB 項目。

較低層級DynamoDbItemEncryptor不支援可搜尋的加密。

如需示範如何使用較低層級 的範例DynamoDbItemEncryptor，請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 item_encrypt_decrypt.rs。

DynamoDB AWS 資料庫加密 SDK 中的屬性動作

屬性動作會決定哪些屬性值會加密和簽署、哪些是僅簽署、哪些是簽署和包含在加密內容中，以及哪些是忽略的。

若要使用 Rust 用戶端指定屬性動作，請使用 物件模型手動定義屬性動作。建立HashMap物件，其中名稱值對代表屬性名稱和指定的動作，以指定您的屬性動作。

指定 ENCRYPT_AND_SIGN來加密和簽署 屬性。指定 SIGN_ONLY 來簽署但不要加密 屬性。指定 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT來簽署 屬性，並將其包含在加密內容中。如果沒有同時簽署屬性，則無法加密該屬性。指定 DO_NOTHING 忽略 屬性。

分割區和排序屬性必須是 SIGN_ONLY或 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。如果您將任何屬性定義為 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT，則分割區和排序屬性也必須是 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。

注意

定義屬性動作之後，您必須定義從簽章中排除哪些屬性。為了在未來更容易新增未簽章的屬性，我們建議您選擇不同的字首 （例如 ":") 來識別未簽章的屬性。在標示DO_NOTHING為定義 DynamoDB 結構描述和屬性動作的所有屬性的屬性名稱中包含此字首。

下列物件模型示範如何使用 Rust ENCRYPT_AND_SIGN SIGN_ONLY用戶端指定 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT、、 和 DO_NOTHING 屬性動作。此範例使用字首 ":" 來識別DO_NOTHING屬性。

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),
]);

DynamoDB AWS 資料庫加密 SDK 中的加密組態

當您使用 AWS 資料庫加密 SDK 時，您必須明確定義 DynamoDB 資料表的加密組態。加密組態中所需的值取決於您是手動或使用註釋的資料類別來定義屬性動作。

下列程式碼片段使用 DynamoDB API 的低階 AWS 資料庫加密 SDK 定義 DynamoDB 資料表加密組態，並允許由不同字首定義的未簽章屬性。

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 optional
    .algorithm_suite_id(
        DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
    )
    .build()?;

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

邏輯資料表名稱

DynamoDB 資料表的邏輯資料表名稱。

邏輯資料表名稱以密碼編譯方式繫結至資料表中存放的所有資料，以簡化 DynamoDB 還原操作。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。您必須一律指定相同的邏輯資料表名稱。若要成功解密，邏輯資料表名稱必須符合加密時指定的名稱。如果您的 DynamoDB 資料表名稱在從備份還原 DynamoDB 資料表之後變更，邏輯資料表名稱可確保解密操作仍可辨識資料表。

允許的未簽署屬性

在您的屬性動作DO_NOTHING中標記的屬性。

允許的未簽章屬性會告知用戶端哪些屬性會從簽章中排除。用戶端假設所有其他屬性都包含在簽章中。然後，在解密記錄時，用戶端會決定需要驗證哪些屬性，以及要從您指定的允許未簽章屬性中忽略哪些屬性。您無法從允許的未簽章屬性中移除屬性。

您可以建立列出所有屬性的陣列，明確定義允許的未簽章DO_NOTHING屬性。您也可以在命名DO_NOTHING屬性時指定不同的字首，並使用字首告訴用戶端哪些屬性未簽署。我們強烈建議指定不同的字首，因為它可簡化未來新增DO_NOTHING屬性的程序。如需詳細資訊，請參閱更新您的資料模型。

如果您未指定所有DO_NOTHING屬性的字首，您可以設定allowedUnsignedAttributes陣列，明確列出用戶端在解密時遇到這些屬性時應該取消簽署的所有屬性。只有在絕對必要時，您才應該明確定義允許的未簽署屬性。

搜尋組態 （選用）

SearchConfig 定義信標版本。

SearchConfig 必須指定 才能使用可搜尋加密或簽章的信標。

演算法套件 （選用）

algorithmSuiteId 定義 AWS 資料庫加密 SDK 使用的演算法套件。

除非您明確指定替代演算法套件，否則 AWS Database Encryption SDK 會使用預設演算法套件。預設演算法套件使用 AES-GCM 演算法搭配金鑰衍生、數位簽章和金鑰承諾。雖然預設演算法套件可能適用於大多數應用程式，但您可以選擇替代演算法套件。例如，某些信任模型將由沒有數位簽章的演算法套件所滿足。如需 AWS 資料庫加密 SDK 支援的演算法套件相關資訊，請參閱 AWS Database Encryption SDK 中支援的演算法套件。

若要選取不含 ECDSA 數位簽章的 AES-GCM 演算法套件，請在資料表加密組態中包含下列程式碼片段。

.algorithm_suite_id(
    DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
)

使用 AWS 資料庫加密 SDK 更新項目

AWS Database Encryption SDK 不支援包含加密或簽章屬性的項目 ddb：UpdateItem。若要更新加密或簽章的屬性，您必須使用 ddb：PutItem。當您在PutItem請求中指定與現有項目相同的主索引鍵時，新項目會完全取代現有項目。