使用適用於 DynamoDB 的 .NET 用戶端加密程式庫 - AWS 資料庫加密 SDK
項目加密程式屬性動作加密組態更新項目

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

本主題說明第 3 版中的一些函數和輔助類別。 適用於 DynamoDB 的 .NET 用戶端加密程式庫的 x 個。

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

項目加密程式

DynamoDB 的 AWS 資料庫加密開發套件在其核心是項目加密程式。您可以使用版本 3。 DynamoDB 的 .NET 用戶端加密程式庫的 x 個，可透過下列方式加密、簽署、驗證和解密 DynamoDB 表格項目。

適用於 DynamoDB API 的低階 AWS 資料庫加密開發套件

您可以使用表格加密組態來建構 DynamoDB 用戶端，該用戶端會自動對 DynamoDB 請求的項目進行加密和簽署。PutItem您可以直接使用此客戶端，也可以構建文檔模型或對象持久性模型。

您必須使用適用於 DynamoDB API 的低階 AWS 資料庫加密開發套件，才能使用可搜尋的加密。

較低級別 DynamoDbItemEncryptor

較低層級會DynamoDbItemEncryptor直接加密、簽署或解密並驗證您的資料表項目，而無需呼叫 DynamoDB。它不會發出 DynamoDB PutItem 或GetItem請求。例如，您可以使用較低層級直DynamoDbItemEncryptor接解密和驗證已擷取的 DynamoDB 項目。如果您使用較低層級的程式設計模型DynamoDbItemEncryptor，我們建議您使用 AWS SDK for .NET 提供與 DynamoDB 通訊的低階程式設計模型。

較低級別DynamoDbItemEncryptor不支持可搜索的加密。

適用於 DynamoDB 的 AWS 資料庫加密開發套件中的屬性動作

屬性動作會決定哪些屬性值已加密和簽署、哪些屬性值僅經過簽署、已簽署並包含在加密前後關聯中，以及忽略哪些值。

若要使用 .NET 用戶端指定屬性動作，請使用物件模型手動定義屬性動作。透過建立一個Dictionary物件，其中名稱-值對代表屬性名稱和指定動作來指定屬性動作。

指定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。

注意

定義屬性動作之後，您必須定義哪些屬性要從簽章中排除。為了方便日後新增 future 簽署的屬性，我們建議您選擇不同的前置詞 (例如 ":「) 來識別未簽署的屬性。在定義 DynamoDB 結構描述和屬性動DO_NOTHING作時標記的所有屬性的屬性名稱中包含此前置詞。

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

注意

若要使用加SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT密動作，您必須使用 3.3 版或更新版本的 AWS 資料庫加密 SDK。在更新要包含的資料模型之前，請先將新版本部署至所有讀取器SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。

var attributeActionsOnEncrypt = new Dictionary<string, CryptoAction>
{
    ["partition_key"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, // The partition attribute must be signed
    ["sort_key"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, // The sort attribute must be signed
    ["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
    ["attribute2"] = CryptoAction.SIGN_ONLY,
    ["attribute3"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT,
    [":attribute4"] = CryptoAction.DO_NOTHING
};

適用於 DynamoDB 的 AWS 資料庫加密開發套件中的加密組態

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

下列程式碼片段使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK 定義 DynamoDB 表格加密組態，並允許透過不同前置詞定義的未簽署屬性。

Dictionary<String, DynamoDbTableEncryptionConfig> tableConfigs =
    new Dictionary<String, DynamoDbTableEncryptionConfig>();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix,
    // Optional: SearchConfig only required if you use beacons
    Search = new SearchConfig
    {
        WriteVersion = 1, // MUST be 1
        Versions = beaconVersions
    }    
};
tableConfigs.Add(ddbTableName, config);
邏輯資料表名稱

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

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

允許不帶正負號

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

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

您可以建立列出所有屬性的陣列，明確定義允許的無正負號DO_NOTHING屬性。您還可以在命名DO_NOTHING屬性時指定不同的前綴，並使用前綴告訴客戶端哪些屬性未簽名。我們強烈建議您指定不同的前置詞，因為這樣可以簡化 future 新增DO_NOTHING屬性的程序。如需詳細資訊，請參閱 更新您的資料模型。

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

搜尋組態 (選擇性)

定SearchConfig義信標版本。

SearchConfig必須指定為使用可搜尋的加密或已簽署的信標。

演算法套件 (選擇性)

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

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

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

AlgorithmSuiteId = DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384

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

UpdateItem對於包含加密或已簽署屬性的項目， AWS 資料庫加密 SDK 不支援 ddb:。若要更新加密或已簽署的屬性，您必須使用 ddb: PutItem。當您在請求中指定與現有項目相同的主PutItem索引鍵時，新項目會完全取代現有項目。更新項目後，您還可以使用 CLOBBER 清除和替換保存時的所有屬性。