.NET 範例

下列範例示範如何使用適用於 DynamoDB 的 .NET 用戶端加密程式庫來保護應用程式中的資料表項目。若要尋找更多範例 （並自行提供），請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 .NET 範例。

下列範例示範如何在新的未填入 Amazon DynamoDB 資料表中設定 DynamoDB 的 .NET 用戶端加密程式庫。如果您想要設定現有的 Amazon DynamoDB 資料表進行用戶端加密，請參閱 將 3.x 版新增至現有資料表。

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

下列範例示範如何使用 DynamoDB API 的低階 AWS 資料庫加密 SDK 搭配 AWS KMS keyring，以自動加密 DynamoDB PutItem請求的用戶端項目並簽署項目。

您可以使用任何支援的 keyring，但我們建議您盡可能使用其中一個 AWS KMS keyring。

請參閱完整的程式碼範例：BasicPutGetExample.cs

步驟 1：建立 AWS KMS keyring

下列範例使用 CreateAwsKmsMrkMultiKeyring建立具有對稱加密 KMS 金鑰的 AWS KMS keyring。此CreateAwsKmsMrkMultiKeyring方法可確保 keyring 可正確處理單一區域和多區域金鑰。

var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

步驟 2：設定屬性動作

下列範例定義attributeActionsOnEncrypt字典，代表資料表項目的範例屬性動作。

注意

下列範例不會將任何屬性定義為 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。如果您指定任何SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT屬性，則分割區和排序屬性也必須是 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。

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

步驟 3：定義從簽章中排除哪些屬性

下列範例假設所有DO_NOTHING屬性共用不同的字首 ":"，並使用字首定義允許的未簽署屬性。用戶端假設簽章中排除任何具有「:」字首的屬性名稱。如需詳細資訊，請參閱Allowed unsigned attributes。

const String unsignAttrPrefix = ":";

步驟 4：定義 DynamoDB 資料表加密組態

下列範例定義代表此 DynamoDB 資料表加密組態的tableConfigs映射。

此範例指定 DynamoDB 資料表名稱做為邏輯資料表名稱。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。如需詳細資訊，請參閱DynamoDB AWS 資料庫加密 SDK 中的加密組態。

注意

若要使用可搜尋加密或簽章的信標，您還必須在加密組態SearchConfig中包含 。

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
};
tableConfigs.Add(ddbTableName, config);

步驟 5：建立新的 AWS SDK DynamoDB 用戶端

下列範例使用步驟 4 TableEncryptionConfigs中的 建立新的 AWS SDK DynamoDB 用戶端。

var ddb = new Client.DynamoDbClient(
    new DynamoDbTablesEncryptionConfig { TableEncryptionConfigs = tableConfigs });

步驟 6：加密和簽署 DynamoDB 資料表項目

下列範例定義一個字典item，代表範例資料表項目，並將該項目放入 DynamoDB 資料表中。項目在傳送至 DynamoDB 之前，會先加密並簽署用戶端。

var item = new Dictionary<String, AttributeValue>
{
    ["partition_key"] = new AttributeValue("BasicPutGetExample"),
    ["sort_key"] = new AttributeValue { N = "0" },
    ["attribute1"] = new AttributeValue("encrypt and sign me!"),
    ["attribute2"] = new AttributeValue("sign me!"),
    [":attribute3"] = new AttributeValue("ignore me!")
};

PutItemRequest putRequest = new PutItemRequest
{
    TableName = ddbTableName,
    Item = item
};

PutItemResponse putResponse = await ddb.PutItemAsync(putRequest);

顯示較多顯示較少

使用較低層級 DynamoDbItemEncryptor

下列範例示範如何使用較低層級 DynamoDbItemEncryptor搭配 AWS KMS keyring 來直接加密和簽署資料表項目。DynamoDbItemEncryptor 不會將項目放入 DynamoDB 資料表。

您可以搭配 DynamoDB 增強型用戶端使用任何支援的 keyring，但我們建議您盡可能使用其中一個 AWS KMS keyring。

注意

較低層級DynamoDbItemEncryptor不支援可搜尋加密。使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK 來使用可搜尋加密。

請參閱完整的程式碼範例：I ItemEncryptDecryptExample.cs

步驟 1：建立 AWS KMS keyring

下列範例使用 CreateAwsKmsMrkMultiKeyring建立具有對稱加密 KMS 金鑰的 AWS KMS keyring。此CreateAwsKmsMrkMultiKeyring方法可確保 keyring 可正確處理單一區域和多區域金鑰。

var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

步驟 2：設定屬性動作

下列範例定義attributeActionsOnEncrypt字典，代表資料表項目的範例屬性動作。

注意

下列範例不會將任何屬性定義為 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。如果您指定任何SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT屬性，則分割區和排序屬性也必須是 SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。

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

步驟 3：定義從簽章中排除哪些屬性

下列範例假設所有DO_NOTHING屬性共用不同的字首 ":"，並使用字首定義允許的未簽署屬性。用戶端假設簽章中排除任何具有「:」字首的屬性名稱。如需詳細資訊，請參閱Allowed unsigned attributes。

String unsignAttrPrefix = ":";

步驟 4：定義DynamoDbItemEncryptor組態

下列範例定義 的組態DynamoDbItemEncryptor。

此範例指定 DynamoDB 資料表名稱做為邏輯資料表名稱。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。如需詳細資訊，請參閱DynamoDB AWS 資料庫加密 SDK 中的加密組態。

var config = new DynamoDbItemEncryptorConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix
};

步驟 5：建立 DynamoDbItemEncryptor

下列範例DynamoDbItemEncryptor使用步驟 4 config中的 建立新的 。

var itemEncryptor = new DynamoDbItemEncryptor(config);

步驟 6：直接加密和簽署資料表項目

下列範例使用 直接加密和簽署項目DynamoDbItemEncryptor。DynamoDbItemEncryptor 不會將項目放在 DynamoDB 資料表中。

var originalItem = new Dictionary<String, AttributeValue>
{
    ["partition_key"] = new AttributeValue("ItemEncryptDecryptExample"),
    ["sort_key"] = new AttributeValue { N = "0" },
    ["attribute1"] = new AttributeValue("encrypt and sign me!"),
    ["attribute2"] = new AttributeValue("sign me!"),
    [":attribute3"] = new AttributeValue("ignore me!")
};

var encryptedItem = itemEncryptor.EncryptItem(
    new EncryptItemInput { PlaintextItem = originalItem }
).EncryptedItem;

顯示較多顯示較少