기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# .NET
이 주제에서는 DynamoDB용 .NET 클라이언트 측 암호화 라이브러리 버전 3.*x*를 설치하고 사용하는 방법을 설명합니다. DynamoDB용 AWS Database Encryption SDK를 사용한 프로그래밍에 대한 자세한 내용은 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에서 지원됩니다.
AWS Database Encryption SDK for DynamoDB의 모든 [프로그래밍 언어](ddb-programming-languages.md) 구현은 상호 운용 가능합니다. 그러나 SDK for .NET 는 목록 또는 맵 데이터 유형에 빈 값을 지원하지 않습니다. 즉, 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) 파일을 참조하세요. DynamoDB용 .NET 클라이언트 측 암호화 라이브러리에는 AWS Key Management Service (AWS KMS) 키를 사용하지 SDK for .NET 않더라도가 필요합니다. 는 SDK for .NET NuGet 패키지와 함께 설치됩니다.
DynamoDB용 .NET 클라이언트 측 암호화 라이브러리 버전 3.*x*는 .NET 6.0 및 .NET Framework net48 이상을 지원합니다.
## .NET을 사용한 디버깅
DynamoDB용 .NET 클라이언트 측 암호화 라이브러리는 로그를 생성하지 않습니다. DynamoDB용 .NET 클라이언트 측 암호화 라이브러리의 예외는 예외 메시지를 생성하지만 스택 트레이스는 생성하지 않습니다.
디버깅에 도움이 되도록 SDK for .NET에서 로그인을 활성화해야 합니다. 의 로그 및 오류 메시지는에서 발생하는 오류를 DynamoDB용 .NET 클라이언트 측 암호화 라이브러리의 오류 SDK for .NET 와 구별하는 데 도움이 될 SDK for .NET 수 있습니다. SDK for .NET 로깅에 대한 도움말은 *AWS SDK for .NET 개발자 안내서*의 [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)
## 항목 암호화 도구
코어에서 AWS Database Encryption SDK for DynamoDB는 항목 암호화 도구입니다. DynamoDB용 .NET 클라이언트 측 암호화 라이브러리 버전 3.*x*를 사용하여 다음과 같은 방법으로 DynamoDB 테이블 항목을 암호화, 서명, 확인 및 해독할 수 있습니다.
**DynamoDB API용 하위 수준 AWS Database Encryption SDK**
[테이블 암호화 구성을](#ddb-net-config-encrypt) 사용하여 DynamoDB `PutItem` 요청으로 클라이언트 측 항목을 자동으로 암호화하고 서명하는 DynamoDB 클라이언트를 구성할 수 있습니다. 이 클라이언트를 직접 사용하거나 [문서 모델](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) 구성할 수 있습니다.
[검색 가능한](searchable-encryption.md) 암호화를 사용하려면 하위 수준 AWS Database Encryption SDK for DynamoDB API를 사용해야 합니다.
**하위 수준 `DynamoDbItemEncryptor`**
하위 수준 `DynamoDbItemEncryptor`에서는 DynamoDB를 호출하지 않고도 테이블 항목을 직접 암호화하고 서명 또는 복호화하고 확인합니다. DynamoDB `PutItem` 또는 `GetItem` 요청을 하지 않습니다. 예를 들어 하위 수준 `DynamoDbItemEncryptor`을 사용하여 이미 검색한 DynamoDB 항목을 직접 복호화하고 확인할 수 있습니다. 하위 수준를 사용하는 경우 DynamoDB와 통신하기 위해에서 SDK for .NET 제공하는 [하위 수준 프로그래밍 모델을](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-low-level) 사용하는 `DynamoDbItemEncryptor`것이 좋습니다.
하위 수준 `DynamoDbItemEncryptor`은 [검색 가능한 암호화](searchable-encryption.md)를 지원하지 않습니다.
## AWS Database Encryption SDK for DynamoDB의 속성 작업
[속성 작업은](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`.
**참고**
속성 작업을 정의한 후에는 서명에서 제외할 속성을 정의해야 합니다. 나중에 서명되지 않은 새 속성을 더 쉽게 추가할 수 있도록 서명되지 않은 속성을 식별할 고유한 접두사(예: "`:`“)를 선택하는 것이 좋습니다. DynamoDB 스키마와 속성 작업을 정의할 때 `DO_NOTHING`로 표시된 모든 속성의 속성 이름에 이 접두사를 포함합니다.
다음 객체 모델은 .NET 클라이언트를 사용하여 `ENCRYPT_AND_SIGN`, `SIGN_ONLY``SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, 및 `DO_NOTHING` 속성 작업을 지정하는 방법을 보여줍니다. 이 예제에서는 접두사 "`:`"를 사용하여 `DO_NOTHING` 속성을 식별합니다.
**참고**
`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` 암호화 작업을 사용하려면 AWS Database Encryption SDK 버전 3.3 이상을 사용해야 합니다. 를 포함하도록 [데이터 모델을 업데이트하기 전에 모든 리더](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
};
```
## AWS Database Encryption SDK for DynamoDB의 암호화 구성
AWS Database Encryption SDK를 사용하는 경우 DynamoDB 테이블에 대한 암호화 구성을 명시적으로 정의해야 합니다. 암호화 구성에 필요한 값은 속성 작업을 수동으로 정의했는지 아니면 주석이 달린 데이터 클래스를 사용하여 정의했는지에 따라 달라집니다.
다음 코드 조각은 하위 수준 AWS Database Encryption SDK for DynamoDB API를 사용하여 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 테이블을 복원](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html)한 후 DynamoDB 테이블 이름이 변경되더라도 논리적 테이블 이름을 사용하면 복호화 작업에서 테이블을 계속 인식할 수 있습니다.
**허용된 서명되지 않은 속성**
속성 작업에 `DO_NOTHING`로 표시된 속성.
허용된 무서명 서명에서 제외되는 속성을 클라이언트에게 알려줍니다. 클라이언트는 다른 모든 속성이 서명에 포함되어 있다고 가정합니다. 그런 다음 레코드를 복호화할 때 클라이언트는 확인해야 할 속성과 지정한 허용된 무서명 속성 중에서 무시할 속성을 결정합니다. 허용된 무서명 속성에서는 속성을 제거할 수 없습니다.
모든 `DO_NOTHING` 속성을 나열하는 배열을 만들어 무서명 허용 속성을 명시적으로 정의할 수 있습니다. `DO_NOTHING` 속성의 이름을 지정할 때 고유한 접두사를 지정하고 이 접두사를 사용하여 무서명 속성을 클라이언트에게 알릴 수도 있습니다. 고유한 접두사를 지정하는 것이 좋습니다. 이렇게 하면 나중에 새 `DO_NOTHING` 속성을 추가하는 프로세스가 단순해지기 때문입니다. 자세한 내용은 [데이터 모델 업데이트](ddb-update-data-model.md) 단원을 참조하십시오.
모든 `DO_NOTHING` 속성에 접두사를 지정하지 않는 경우 클라이언트가 복호화 시 서명되지 않을 것으로 예상되는 모든 속성을 명시적으로 나열하는 `allowedUnsignedAttributes` 배열을 구성할 수 있습니다. 반드시 필요한 경우에만 허용된 서명되지 않은 속성을 명시적으로 정의해야 합니다.
**검색 구성(선택 사항)**
`SearchConfig`는 [비컨 버전](using-beacons.md#beacon-version)을 정의합니다.
[검색 가능한 암호화](searchable-encryption.md) 또는 [서명된 비컨](configure.md#signed-beacons)을 사용하려면 `SearchConfig`를 지정해야 합니다.
**알고리즘 제품군(선택 사항)**
`algorithmSuiteId`은 AWS Database Encryption SDK가 사용하는 알고리즘 제품군을 정의합니다.
대체 알고리즘 제품군을 명시적으로 지정하지 않는 한 AWS Database Encryption SDK는 [기본 알고리즘 제품군](supported-algorithms.md#recommended-algorithms)을 사용합니다. 기본 알고리즘 제품군은 키 도출, [디지털 서명](concepts.md#digital-sigs) 및 [키 커밋](concepts.md#key-commitment)과 함께 AES-GCM 알고리즘을 사용합니다. 기본 알고리즘 제품군이 대부분의 애플리케이션에 적합할 가능성이 높지만 대체 알고리즘 제품군을 선택할 수도 있습니다. 예를 들어, 일부 신뢰 모델은 디지털 서명이 없는 알고리즘 제품군으로 충분할 수 있습니다. AWS Database Encryption SDK가 지원하는 알고리즘 제품군에 대한 자세한 내용은 섹션을 참조하세요[AWS Database Encryption 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 Database Encryption SDK로 항목 업데이트
AWS Database Encryption 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 사용
다음 예제에서는 하위 수준 AWS Database Encryption SDK for DynamoDB API를 [AWS KMS 키링](use-kms-keyring.md)과 함께 사용하여 DynamoDB `PutItem` 요청으로 클라이언트 측 항목을 자동으로 암호화하고 서명하는 방법을 보여줍니다.
지원되는 모든 [키링](keyrings.md)을 사용할 수 있지만 가능하면 AWS KMS 키링 중 하나를 사용하는 것이 좋습니다.
**전체 코드 샘플**: [BasicPutGetExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/BasicPutGetExample.cs) 참조
**1단계: AWS KMS 키링 생성**
다음 예제에서는 `CreateAwsKmsMrkMultiKeyring`를 사용하여 대칭 암호화 KMS AWS KMS 키로 키링을 생성합니다. 이 `CreateAwsKmsMrkMultiKeyring` 방법을 사용하면 키링이 단일 리전 키와 다중 리전 키를 모두 올바르게 처리할 수 있습니다.
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**2단계: 속성 작업 구성**
다음 예제에서는 테이블 항목에 대한 샘플 [속성 작업을](concepts.md#crypt-actions) 나타내는 `attributeActionsOnEncrypt` 사전을 정의합니다.
다음 예제에서는 속성을 로 정의하지 않습니다`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 테이블 이름을 논리적 테이블 이름으로 지정하는 것이 좋습니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB의 암호화 구성](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`
다음 예제는 [AWS KMS 키링](use-kms-keyring.md)이 있는 하위 수준 `DynamoDbItemEncryptor`을 사용하여 테이블 항목을 직접 암호화하고 서명하는 방법을 보여줍니다. `DynamoDbItemEncryptor`는 DynamoDB 테이블에 항목을 배치하지 않습니다.
DynamoDB Enhanced Client에서 지원되는 모든 [키링](keyrings.md)을 사용할 수 있지만 가능하면 AWS KMS 키링 중 하나를 사용하는 것이 좋습니다.
**참고**
하위 수준 `DynamoDbItemEncryptor`은 [검색 가능한 암호화](searchable-encryption.md)를 지원하지 않습니다. 하위 수준 AWS Database Encryption SDK for DynamoDB API를 사용하여 검색 가능한 암호화를 사용합니다.
**전체 코드 샘플**: [ItemEncryptDecryptExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/itemencryptor/ItemEncryptDecryptExample.cs) 참조
**1단계: AWS KMS 키링 생성**
다음 예제에서는 `CreateAwsKmsMrkMultiKeyring`를 사용하여 대칭 암호화 KMS AWS KMS 키로 키링을 생성합니다. 이 `CreateAwsKmsMrkMultiKeyring` 방법을 사용하면 키링이 단일 리전 키와 다중 리전 키를 모두 올바르게 처리할 수 있습니다.
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**2단계: 속성 작업 구성**
다음 예제에서는 테이블 항목에 대한 샘플 [속성 작업을](concepts.md#crypt-actions) 나타내는 `attributeActionsOnEncrypt` 사전을 정의합니다.
다음 예제에서는 속성을 로 정의하지 않습니다`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 테이블 이름을 논리적 테이블 이름으로 지정하는 것이 좋습니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB의 암호화 구성](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` 생성**
다음 예제에서는 **4단계**의 `config`를 사용하여 새 `DynamoDbItemEncryptor`을 만듭니다.
```
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용 AWS Database Encryption SDK를 사용하도록 기존 DynamoDB 테이블 구성
DynamoDB용 .NET 클라이언트 측 암호화 라이브러리 버전 3.*x*를 사용하면 클라이언트 측 암호화를 위해 기존 Amazon DynamoDB 테이블을 구성할 수 있습니다. 이 주제에서는 채워진 기존 DynamoDB 테이블에 버전 3.*x*를 추가하기 위해 수행해야 하는 세 가지 단계에 대한 지침을 제공합니다.
## 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`을 지정합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB의 속성 작업](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. [키링](keyrings.md) 생성**
다음 예제에서는 [AWS KMS 키링](use-kms-keyring.md)을 생성합니다. AWS KMS 키링은 대칭 암호화 또는 비대칭 RSA AWS KMS keys 를 사용하여 데이터 키를 생성, 암호화 및 복호화합니다.
이 예제에서는 `CreateMrkMultiKeyring`를 사용하여 대칭 암호화 KSM 키를 포함한 AWS KMS 키링을 생성합니다. 이 `CreateAwsKmsMrkMultiKeyring` 방법을 사용하면 키링이 단일 리전 키와 다중 리전 키를 모두 올바르게 처리할 수 있습니다.
```
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`을 일반 텍스트 오버라이드로 지정해야 합니다. 이 정책은 계속해서 일반 텍스트 항목을 읽고 쓰고, 암호화된 항목을 읽고, 클라이언트가 암호화된 항목을 쓸 수 있도록 준비시킵니다.
테이블 암호화 구성에 포함된 값에 대한 자세한 내용은 섹션을 참조하세요[AWS Database Encryption SDK for DynamoDB의 암호화 구성](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);
```