本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# .NET
本主題說明如何安裝和使用適用於 DynamoDB 的 .NET 用戶端加密程式庫的 3.*x* 版。如需使用 DynamoDB AWS 資料庫加密開發套件進行程式設計的詳細資訊，請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 .[NET 範例](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/)。
DynamoDB 的 .NET 用戶端加密程式庫適用於以 C\$1 和其他 .NET 程式設計語言撰寫應用程式的開發人員。Windows、macOS 和 Linux 都提供支援。
適用於 DynamoDB 的 AWS Database Encryption SDK 的所有[程式設計語言](ddb-programming-languages.md)實作皆可互通。不過， 適用於 .NET 的 SDK 不支援清單或映射資料類型的空白值。這表示如果您使用適用於 DynamoDB 的 Java 用戶端加密程式庫來撰寫包含清單或映射資料類型空白值的項目，則無法使用適用於 DynamoDB 的 .NET 用戶端加密程式庫解密和讀取該項目。
**Topics**
+ [安裝](#ddb-net-install)
+ [除錯](#ddb-net-debugging)
+ [使用 .NET 用戶端](ddb-net-using.md)
+ [.NET 範例](ddb-net-examples.md)
+ [將 3.x 版新增至現有資料表](ddb-net-config-existing-table.md)
## 安裝適用於 DynamoDB 的 .NET 用戶端加密程式庫
DynamoDB 的 .NET 用戶端加密程式庫可作為 NuGet 中的 [AWS.Cryptography.DbEncryptionSDK.DynamoDb](https://www.nuget.org/packages/AWS.Cryptography.DbEncryptionSDK.DynamoDb/) 套件。如需安裝和建置程式庫的詳細資訊，請參閱 aws-database-encryption-sdk-dynamodb 儲存庫中的 [.NET README.md](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/runtimes/net/README.md) 檔案。 適用於 .NET 的 SDK 即使您未使用 AWS Key Management Service (AWS KMS) 金鑰，適用於 DynamoDB 的 .NET 用戶端加密程式庫也需要 。與 NuGet 適用於 .NET 的 SDK 套件一起安裝。
DynamoDB 的 .NET 用戶端加密程式庫版本 3.*x* 支援 .NET 6.0 和 .NET Framework net48 及更新版本。
## 使用 .NET 進行偵錯
DynamoDB 的 .NET 用戶端加密程式庫不會產生任何日誌。DynamoDB 的 .NET 用戶端加密程式庫中的例外狀況會產生例外狀況訊息，但不會產生堆疊追蹤。
為了協助您偵錯，請務必在 中啟用記錄 適用於 .NET 的 SDK。的日誌和錯誤訊息 適用於 .NET 的 SDK 可協助您區分 中產生的錯誤 適用於 .NET 的 SDK 與 DynamoDB 的 .NET 用戶端加密程式庫中的錯誤。如需 適用於 .NET 的 SDK 記錄的說明，請參閱《 *適用於 .NET 的 AWS SDK 開發人員指南*》中的 [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-other.html#config-setting-awslogging)。（若要查看主題，請展開**開啟以檢視 .NET Framework 內容**區段。)
# 使用適用於 DynamoDB 的 .NET 用戶端加密程式庫
本主題說明 DynamoDB 的 .NET 用戶端加密程式庫 3.*x* 版中的一些函數和協助程式類別。
如需使用適用於 DynamoDB 的 .NET 用戶端加密程式庫進行程式設計的詳細資訊，請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 .[NET 範例](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/)。
**Topics**
+ [項目加密程式](#ddb-net-item-encryptors)
+ [屬性動作](#ddb-net-attribute-actions)
+ [加密組態](#ddb-net-config-encrypt)
+ [更新項目](#ddb-net-update-items)
## 項目加密程式
DynamoDB AWS 資料庫加密開發套件的核心是項目加密程式。您可以使用適用於 DynamoDB 的 .NET 用戶端加密程式庫 3.*x* 版，以下列方式加密、簽署、驗證和解密 DynamoDB 資料表項目。
**適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK**
您可以使用[資料表加密組態](#ddb-net-config-encrypt)來建構 DynamoDB 用戶端，以使用 DynamoDB `PutItem`請求自動加密和簽署用戶端的項目。您可以直接使用此用戶端，也可以建構[文件模型](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-document)或[物件持久性模型](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-object-persistence)。
您必須使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK，才能使用[可搜尋的加密](searchable-encryption.md)。
**較低層級 `DynamoDbItemEncryptor`**
較低層級會`DynamoDbItemEncryptor`直接加密和簽署或解密，並驗證您的資料表項目，而無需呼叫 DynamoDB。它不會發出 DynamoDB `PutItem`或 `GetItem` 請求。例如，您可以使用較低層級`DynamoDbItemEncryptor`直接解密和驗證您已擷取的 DynamoDB 項目。如果您使用較低層級的 `DynamoDbItemEncryptor`，我們建議您使用 適用於 .NET 的 SDK 提供的[低階程式設計模型](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-low-level)來與 DynamoDB 通訊。
較低層級`DynamoDbItemEncryptor`不支援[可搜尋的加密](searchable-encryption.md)。
## DynamoDB AWS 資料庫加密 SDK 中的屬性動作
[屬性動作](concepts.md#crypt-actions)會決定哪些屬性值經過加密和簽署、哪些屬性值只經過簽署、哪些屬性值經過簽署並包含在加密內容中，以及哪些屬性值會被忽略。
若要使用 .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`。
**注意**
定義屬性動作之後，您必須定義要從簽章中排除哪些屬性。為了在未來更容易新增未簽章的屬性，我們建議您選擇不同的字首 （例如 "`:`") 來識別未簽章的屬性。將此字首包含在標示`DO_NOTHING`為定義 DynamoDB 結構描述和屬性動作的所有屬性的屬性名稱中。
下列物件模型示範如何使用 `ENCRYPT_AND_SIGN`.NET `SIGN_ONLY`用戶端指定 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`、、 和 `DO_NOTHING` 屬性動作。此範例使用字首「`:`」來識別`DO_NOTHING`屬性。
**注意**
若要使用`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`密碼編譯動作，您必須使用 3.3 版或更新版本的 AWS 資料庫加密 SDK。將[您的資料模型更新](ddb-update-data-model.md)為包含 之前，將新版本部署至所有讀者`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。
```
var attributeActionsOnEncrypt = new Dictionary
{
["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 資料庫加密 SDK 中的加密組態
使用 AWS 資料庫加密 SDK 時，您必須明確定義 DynamoDB 資料表的加密組態。加密組態中所需的值取決於您是手動還是使用註釋的資料類別來定義屬性動作。
下列程式碼片段使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK 來定義 DynamoDB 資料表加密組態，並允許由不同字首定義的未簽章屬性。
```
Dictionary tableConfigs =
new Dictionary();
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 資料表](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html)之後變更，邏輯資料表名稱可確保解密操作仍可辨識資料表。
**允許的未簽署屬性**
在您的屬性動作`DO_NOTHING`中標記的屬性。
允許的未簽章屬性會告知用戶端，哪些屬性會從簽章中排除。用戶端假設所有其他屬性都包含在簽章中。然後，在解密記錄時，用戶端會決定需要驗證哪些屬性，以及從您指定的允許未簽署屬性中忽略哪些屬性。您無法從允許的未簽署屬性中移除屬性。
您可以建立列出所有屬性的陣列，明確定義允許的未簽章`DO_NOTHING`屬性。您也可以在命名`DO_NOTHING`屬性時指定不同的字首，並使用字首告訴用戶端哪些屬性未簽署。我們強烈建議指定不同的字首，因為它可簡化未來新增`DO_NOTHING`屬性的程序。如需詳細資訊，請參閱[更新資料模型](ddb-update-data-model.md)。
如果您未為所有`DO_NOTHING`屬性指定字首，您可以設定`allowedUnsignedAttributes`陣列，明確列出用戶端在解密時遇到這些屬性時應取消簽署的所有屬性。只有在絕對必要時，才應該明確定義允許的未簽署屬性。
**搜尋組態 （選用）**
`SearchConfig` 定義[信標版本](using-beacons.md#beacon-version)。
`SearchConfig` 必須指定 才能使用[可搜尋加密](searchable-encryption.md)或[簽章的信標](configure.md#signed-beacons)。
**演算法套件 （選用）**
`algorithmSuiteId` 定義 AWS 資料庫加密 SDK 使用的演算法套件。
除非您明確指定替代演算法套件，否則 AWS 資料庫加密 SDK 會使用[預設演算法套件](supported-algorithms.md#recommended-algorithms)。預設演算法套件使用 AES-GCM 演算法搭配金鑰衍生、[數位簽章](concepts.md#digital-sigs)和[金鑰承諾](concepts.md#key-commitment)。雖然預設演算法套件可能適用於大多數應用程式，但您可以選擇替代演算法套件。例如，某些信任模型將由沒有數位簽章的演算法套件滿足。如需有關 AWS 資料庫加密 SDK 支援的演算法套件的資訊，請參閱 [AWS 資料庫加密 SDK 中支援的演算法套件](supported-algorithms.md)。
若要選取[不含 ECDSA 數位簽章的 AES-GCM 演算法套件](supported-algorithms.md#other-algorithms)，請在資料表加密組態中包含下列程式碼片段。
```
AlgorithmSuiteId = DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384
```
## 使用 AWS 資料庫加密 SDK 更新項目
AWS 資料庫加密 SDK 不支援包含加密或簽章屬性的項目 [ddb：UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)。若要更新加密或簽章的屬性，您必須使用 [ddb：PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)。當您在`PutItem`請求中指定與現有項目相同的主索引鍵時，新項目會完全取代現有項目。您也可以在更新項目後，使用 [CLOBBER](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.SaveBehavior.html#CLOBBER) 在儲存時清除和取代所有屬性。
# .NET 範例
下列範例示範如何使用適用於 DynamoDB 的 .NET 用戶端加密程式庫來保護應用程式中的資料表項目。若要尋找更多範例 （並自行提供），請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 .[NET 範例](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/net/src)。
下列範例示範如何在未填入的新 Amazon DynamoDB 資料表中設定 DynamoDB 的 .NET 用戶端加密程式庫。如果您想要設定現有的 Amazon DynamoDB 資料表進行用戶端加密，請參閱 [將 3.x 版新增至現有資料表](ddb-net-config-existing-table.md)。
**Topics**
+ [使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK](#ddb-net-lowlevel-API-example)
+ [使用較低層級 `DynamoDbItemEncryptor`](#ddb-net-itemencryptor)
## 使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK
下列範例示範如何使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK 搭配 [AWS KMS keyring](use-kms-keyring.md)，以自動加密和簽署 DynamoDB `PutItem`請求的用戶端項目。
您可以使用任何支援的 [keyring](keyrings.md)，但我們建議您盡可能使用其中一個 AWS KMS keyring。
**請參閱完整的程式碼範例**：[BasicPutGetExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/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` 字典，代表資料表項目的範例[屬性動作](concepts.md#crypt-actions)。
下列範例不會將任何屬性定義為 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。如果您指定任何`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`屬性，則分割區和排序屬性也必須是 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。
```
var attributeActionsOnEncrypt = new Dictionary
{
["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](ddb-net-using.md#net-allowed-unauth)。
```
const String unsignAttrPrefix = ":";
```
**步驟 4：定義 DynamoDB 資料表加密組態**
下列範例定義代表此 DynamoDB 資料表加密組態的`tableConfigs`映射。
此範例會將 DynamoDB 資料表名稱指定為[邏輯資料表名稱](ddb-net-using.md#net-logical-table-name)。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。如需詳細資訊，請參閱[DynamoDB AWS 資料庫加密 SDK 中的加密組態](ddb-net-using.md#ddb-net-config-encrypt)。
若要使用[可搜尋加密](searchable-encryption.md)或[已簽章的信標](configure.md#signed-beacons)，您還必須在加密組態[`SearchConfig`](ddb-java-using.md#ddb-search-config)中包含 。
```
Dictionary tableConfigs =
new Dictionary();
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
{
["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](use-kms-keyring.md) 來直接加密和簽署資料表項目。`DynamoDbItemEncryptor` 不會將項目放在 DynamoDB 資料表中。
您可以搭配 DynamoDB 增強型用戶端使用任何支援的 [keyring](keyrings.md)，但我們建議您盡可能使用其中一個 AWS KMS keyring。
**注意**
較低層級`DynamoDbItemEncryptor`不支援[可搜尋的加密](searchable-encryption.md)。使用適用於 DynamoDB API 的低階 AWS 資料庫加密 SDK 來使用可搜尋的加密。
**請參閱完整的程式碼範例**： [ItemEncryptDecryptExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/itemencryptor/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` 字典，代表資料表項目的範例[屬性動作](concepts.md#crypt-actions)。
下列範例不會將任何屬性定義為 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。如果您指定任何`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`屬性，則分割區和排序屬性也必須是 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。
```
var attributeActionsOnEncrypt = new Dictionary
{
["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](ddb-net-using.md#net-allowed-unauth)。
```
String unsignAttrPrefix = ":";
```
**步驟 4：定義`DynamoDbItemEncryptor`組態**
下列範例定義 的組態`DynamoDbItemEncryptor`。
此範例指定 DynamoDB 資料表名稱做為[邏輯資料表名稱](ddb-net-using.md#net-logical-table-name)。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。如需詳細資訊，請參閱[DynamoDB AWS 資料庫加密 SDK 中的加密組態](ddb-net-using.md#ddb-net-config-encrypt)。
```
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
{
["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;
```
# 設定現有的 DynamoDB 資料表以使用適用於 DynamoDB 的 AWS 資料庫加密 SDK
使用適用於 DynamoDB 的 .NET 用戶端加密程式庫的 3.*x* 版，您可以將現有的 Amazon DynamoDB 資料表設定為用戶端加密。本主題提供將 3.*x* 版新增至現有填入的 DynamoDB 資料表的三個步驟指引。
## 步驟 1：準備讀取和寫入加密的項目
請完成下列步驟，以準備您的 AWS Database Encryption SDK 用戶端讀取和寫入加密的項目。部署下列變更後，用戶端將繼續讀取和寫入純文字項目。它不會加密或簽署寫入資料表的任何新項目，但一旦加密項目出現，它就能夠立即解密。這些變更可讓用戶端開始[加密新項目](#ddb-net-add-step2)。您必須先將下列變更部署到每個讀取器，才能繼續下一個步驟。
**1. 定義您的[屬性動作](concepts.md#crypt-actions)**
建立物件模型以定義要加密和簽署哪些屬性值、僅簽署哪些屬性值，以及將忽略哪些屬性值。
根據預設，主要金鑰屬性會經過簽署但未加密 (`SIGN_ONLY`)，而所有其他屬性則會經過加密和簽署 (`ENCRYPT_AND_SIGN`)。
指定 `ENCRYPT_AND_SIGN` 來加密和簽署 屬性。指定 `SIGN_ONLY`簽署但不加密 屬性。指定 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` 以簽署和屬性，並將其包含在加密內容中。如果沒有同時簽署屬性，則無法加密該屬性。指定 `DO_NOTHING` 以忽略 屬性。如需詳細資訊，請參閱[DynamoDB AWS 資料庫加密 SDK 中的屬性動作](ddb-net-using.md#ddb-net-attribute-actions)。
如果您指定任何`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`屬性，則分割區和排序屬性也必須是 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。
```
var attributeActionsOnEncrypt = new Dictionary
{
["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
};
```
**2. 定義將從簽章中排除哪些屬性**
下列範例假設所有`DO_NOTHING`屬性共用不同的字首「`:`」，並使用字首定義允許的未簽章屬性。用戶端將假設具有「`:`」字首的任何屬性名稱已從簽章中排除。如需詳細資訊，請參閱[Allowed unsigned attributes](ddb-net-using.md#net-allowed-unauth)。
```
const String unsignAttrPrefix = ":";
```
**3. 建立 [keyring](keyrings.md)**
下列範例會建立 [AWS KMS keyring](use-kms-keyring.md)。 AWS KMS keyring 使用對稱加密或非對稱 RSA AWS KMS keys 來產生、加密和解密資料金鑰。
此範例使用 `CreateMrkMultiKeyring`建立具有對稱加密 KMS 金鑰的 AWS KMS keyring。`CreateAwsKmsMrkMultiKeyring` 方法可確保 keyring 可正確處理單一區域和多區域金鑰。
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**4. 定義 DynamoDB 資料表加密組態 **
下列範例會定義代表此 DynamoDB 資料表加密組態的`tableConfigs`映射。
此範例指定 DynamoDB 資料表名稱做為[邏輯資料表名稱](ddb-net-using.md#net-logical-table-name)。當您第一次定義加密組態時，強烈建議指定您的 DynamoDB 資料表名稱做為邏輯資料表名稱。
您必須指定 `FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT`做為純文字覆寫。此政策會繼續讀取和寫入純文字項目、讀取加密項目，以及準備用戶端寫入加密項目。
如需資料表加密組態中包含之值的詳細資訊，請參閱 [DynamoDB AWS 資料庫加密 SDK 中的加密組態](ddb-java-using.md#ddb-config-encrypt)。
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix,
PlaintextOverride = FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```
**5. 建立新的 AWS SDK DynamoDB 用戶端**
他遵循範例使用步驟 4 `TableEncryptionConfigs`中的 建立新的 AWS SDK DynamoDB 用戶端。 ****
```
var ddb = new Client.DynamoDbClient(
new DynamoDbTablesEncryptionConfig { TableEncryptionConfigs = tableConfigs });
```
## 步驟 2：寫入加密和簽章的項目
更新資料表加密組態中的純文字政策，以允許用戶端寫入加密和簽署的項目。部署下列變更之後，用戶端會根據您在**步驟 1 **中設定的屬性動作來加密和簽署新項目。用戶端將能夠讀取純文字項目，以及加密和簽署的項目。
在繼續[步驟 3](#ddb-net-add-step3) 之前，您必須加密和簽署資料表中的所有現有純文字項目。您可以執行沒有單一指標或查詢來快速加密現有的純文字項目。使用對您的系統最有意義的程序。例如，您可以使用慢速掃描資料表的非同步程序，並使用您定義的屬性動作和加密組態重寫項目。若要識別資料表中的純文字項目，建議您掃描所有不包含 AWS Database Encryption SDK 在加密`aws_dbe_head`和簽署項目時新增至項目的 和 `aws_dbe_foot` 屬性的項目。
下列範例會從**步驟 1 **更新資料表加密組態。您必須使用 更新純文字覆寫`FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT`。此政策會繼續讀取純文字項目，但也會讀取和寫入加密的項目。使用更新的 建立新的 AWS SDK DynamoDB 用戶端`TableEncryptionConfigs`。
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix,
PlaintextOverride = FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```
## 步驟 3：僅讀取加密和已簽章的項目
在您加密並簽署所有項目之後，請更新資料表加密組態中的純文字覆寫，以僅允許用戶端讀取和寫入加密和簽署的項目。部署下列變更之後，用戶端會根據您在**步驟 1 **中設定的屬性動作來加密和簽署新項目。用戶端只能讀取加密和簽署的項目。
下列範例會從**步驟 2 **更新資料表加密組態。您可以使用 更新純文字覆寫，`FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT`或從組態中移除純文字政策。根據預設，用戶端只會讀取和寫入加密和簽署的項目。使用更新的 建立新的 AWS SDK DynamoDB 用戶端`TableEncryptionConfigs`。
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix,
// Optional: you can also remove the plaintext policy from your configuration
PlaintextOverride = FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```