기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon DynamoDB Encryption Client에서 사용할 수 있는 프로그래밍 언어
**참고**
클라이언트측 암호화 라이브러리의 [이름이 AWS Database Encryption SDK로 변경되었습니다](DDBEC-rename.md). 다음 주제에서는 Java용 DynamoDB Encryption Client 버전 1.*x*\$12.*x* 와 Python용 DynamoDB Encryption Client 버전 1.*x*\$13.*x*에 대한 정보를 제공합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB 버전 지원](legacy-dynamodb-encryption-client.md#legacy-support)을 참조하세요.
Amazon DynamoDB Encryption Client는 다음 프로그래밍 언어에 사용할 수 있습니다. 언어별 라이브러리는 다양하지만 결과 구현은 상호 운용이 가능합니다. 예를 들어 Java 클라이언트로 항목을 암호화(및 서명)하고 Python 클라이언트로 항목을 복호화할 수 있습니다.
자세한 내용은 해당 주제를 참조하세요.
**Topics**
+ [Java](java.md)
+ [Python](python.md)
# Amazon DynamoDB Encryption Client for Java
**참고**
클라이언트측 암호화 라이브러리의 [이름이 AWS Database Encryption SDK로 변경되었습니다](DDBEC-rename.md). 다음 주제에서는 Java용 DynamoDB Encryption Client 버전 1.*x*\$12.*x* 와 Python용 DynamoDB Encryption Client 버전 1.*x*\$13.*x*에 대한 정보를 제공합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB 버전 지원](legacy-dynamodb-encryption-client.md#legacy-support)을 참조하세요.
이 주제에서는 Amazon DynamoDB Encryption Client for Java를 설치하고 사용하는 방법을 설명합니다. DynamoDB Encryption Client를 사용한 프로그래밍에 대한 자세한 내용은 [Java 예제](java-examples.md), GitHub의 aws-dynamodb-encryption-java 리포지토리에 있는 [예제](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) 및 DynamoDB Encryption Client용 [Javadoc](https://aws.github.io/aws-dynamodb-encryption-java/)을 참조하세요.
**참고**
Java용 DynamoDB Encryption Client 버전 1.*x*.*x*는 2022년 7월부터 [지원 종료 단계](what-is-database-encryption-sdk.md#support)에 있습니다. 가능한 한 빨리 최신 버전으로 업그레이드하세요.
**Topics**
+ [사전 조건](#java-prerequisites)
+ [설치](#java-installation)
+ [DynamoDB Encryption Client for Java 사용](java-using.md)
+ [Java 예제](java-examples.md)
## 사전 조건
Amazon DynamoDB Encryption Client for Java를 설치하기 전에 다음 사전 조건이 충족되었는지 확인합니다.
**Java 개발 환경**
Java 8 이상이 필요합니다. Oracle 웹 사이트에서 [Java SE 다운로드](https://www.oracle.com/java/technologies/downloads/)로 이동한 다음 Java SE Development Kit(JDK)를 다운로드하여 설치합니다.
Oracle JDK를 사용하는 경우 [Java Cryptography Extension(JCE) Unlimited Strength Jurisdiction Policy File](http://www.oracle.com/java/technologies/javase-jce8-downloads.html)도 다운로드하여 설치해야 합니다.
**AWS SDK for Java**
애플리케이션이 DynamoDB와 상호 작용 AWS SDK for Java 하지 않더라도 DynamoDB Encryption Client에는의 DynamoDB 모듈이 필요합니다. 전체 SDK를 설치하거나 이 모듈만 설치할 수 있습니다. Maven을 사용하는 경우 `pom.xml` 파일에 `aws-java-sdk-dynamodb`을 추가합니다.
설치 및 구성에 대한 자세한 내용은 섹션을 AWS SDK for Java참조하세요[AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/getting-started.html).
## 설치
다음과 같은 방법으로 Amazon DynamoDB Encryption Client for Java를 설치할 수 있습니다.
**직접**
Amazon DynamoDB Encryption Client for Java를 설치하려면 [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/) GitHub 리포지토리를 복제하거나 다운로드하세요.
**Apache Maven 사용**
Amazon DynamoDB Encryption Client for Java는 다음 종속성 정의와 함께 [Apache Maven](https://maven.apache.org/)을 통해 사용할 수 있습니다.
```
com.amazonaws
aws-dynamodb-encryption-java
version-number
```
SDK를 설치한 후에는 이 가이드의 예제 코드와 GitHub의 [DynamoDB Encryption Client Javadoc](https://aws.github.io/aws-dynamodb-encryption-java/)을 살펴보는 것부터 시작합니다.
# DynamoDB Encryption Client for Java 사용
**참고**
클라이언트측 암호화 라이브러리의 [이름이 AWS Database Encryption SDK로 변경되었습니다](DDBEC-rename.md). 다음 주제에서는 Java용 DynamoDB Encryption Client 버전 1.*x*\$12.*x* 와 Python용 DynamoDB Encryption Client 버전 1.*x*\$13.*x*에 대한 정보를 제공합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB 버전 지원](legacy-dynamodb-encryption-client.md#legacy-support)을 참조하세요.
이 주제에서는 다른 프로그래밍 언어 구현에서는 찾을 수 없는 Java의 DynamoDB Encryption Client 기능 중 일부를 설명합니다.
DynamoDB Encryption Client를 사용한 프로그래밍에 대한 자세한 내용은 [Java 예제](java-examples.md), GitHub에 대한 `aws-dynamodb-encryption-java repository`의 [예제](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) 및 DynamoDB Encryption Client용 [Javadoc](https://aws.github.io/aws-dynamodb-encryption-java/)를 참조하세요.
**Topics**
+ [항목 암호화 도구](#attribute-encryptor)
+ [저장 동작 구성](#save-behavior)
+ [Java의 속성 작업](#attribute-actions-java)
+ [테이블 이름 재정의](#override-table-name)
## 항목 암호화 도구: AttributeEncryptor 및 DynamoDBEncryptor
Java의 DynamoDB Encryption Client에는 두 개의 [항목 암호화 도구](DDBEC-legacy-concepts.md#item-encryptor), 즉 하위 수준 [DynamoDBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html) 및 [AttributeEncryptor](#attribute-encryptor)가 있습니다.
`AttributeEncryptor`는 DynamoDB Encryption Client의에서 [DynamoDBMapper](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html)를 사용하는 데 도움이 `DynamoDB Encryptor` 되는 헬퍼 클래스입니다. AWS SDK for Java DynamoDB `DynamoDBMapper`와 함께 `AttributeEncryptor`를 사용하면 사용자가 항목을 저장할 때 항목을 사용자 모르게 암호화하고 서명합니다. 또한 사용자가 항목을 로드할 때 항목을 사용자 모르게 확인하고 복호화합니다.
## 저장 동작 구성
`AttributeEncryptor` 및 `DynamoDBMapper`를 사용하여 서명만 있거나 암호화 및 서명된 속성이 있는 테이블 항목을 추가하거나 교체할 수 있습니다. 이러한 작업의 경우 다음 예와 같이 `PUT` 저장 동작을 사용하도록 구성하는 것이 좋습니다. 그렇지 않으면 데이터를 복호화하지 못할 수 있습니다.
```
DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.PUT).build();
DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));
```
테이블 항목에서 모델링된 속성만 업데이트하는 기본 저장 동작을 사용하는 경우 모델링되지 않은 속성은 서명에 포함되지 않으며 테이블 쓰기에 의해 변경되지 않습니다. 따라서 모델링되지 않은 속성을 포함하지 않기 때문에 나중에 모든 속성을 읽을 때 서명이 검증되지 않습니다.
`CLOBBER` 저장 동작을 사용할 수도 있습니다. 이 동작은 낙관적 잠금을 비활성화하고 테이블의 항목을 덮어쓴다는 점을 제외하면 `PUT` 저장 동작과 동일합니다.
서명 오류를 방지하기 위해 DynamoDB Encryption Client는 `AttributeEncryptor`를 저장 동작이 `CLOBBER` 또는 `PUT`로 구성되지 않은 `DynamoDBMapper`와 함께 사용하는 경우 런타임 예외를 발생시킵니다.
예제에 사용된 이 코드를 보려면 [DynamoDBMapper 사용](java-examples.md#java-example-dynamodb-mapper) 및 GitHub의 `aws-dynamodb-encryption-java` 리포지토리에 있는 [AwsKmsEncryptedObject.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedObject.java) 예제를 참조하세요.
## Java의 속성 작업
[속성 작업](DDBEC-legacy-concepts.md#legacy-attribute-actions)은 암호화 및 서명되는 속성 값, 서명만 되는 속성 값 및 무시되는 속성 값을 결정합니다. 속성 작업을 지정하는 데 사용하는 메서드는 `DynamoDBMapper` 및 `AttributeEncryptor`, 또는 하위 수준 [DynamoDBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html) 중 어느 것을 사용하는지에 따라 달라집니다.
**중요**
속성 작업을 사용하여 테이블 항목을 암호화한 후 데이터 모델에서 속성을 추가하거나 제거하면 서명 검증 오류가 발생하여 데이터를 복호화하지 못할 수 있습니다. 자세한 내용은 [데이터 모델 변경](data-model.md) 단원을 참조하십시오.
### DynamoDBMapper에 대한 속성 작업
`DynamoDBMapper` 및 `AttributeEncryptor`를 사용하는 경우 주석을 사용하여 속성 작업을 지정합니다. DynamoDB Encryption Client는 속성 유형을 정의하는 [표준 DynamoDB 속성 주석](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Annotations.html)을 사용하여 속성을 보호하는 방법을 결정합니다. 기본적으로 기본 키(서명되지만 암호화되지 않음)를 제외하고는 모든 속성이 암호화 및 서명됩니다.
**참고**
서명할 수 있고 서명해야 하더라도 [@DynamoDBVersionAttribute 주석](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.OptimisticLocking.html)을 사용하여 속성 값을 암호화하지 마십시오. 그렇지 않으면 해당 값을 사용하는 조건이 의도하지 않은 영향을 미치게 됩니다.
```
// Attributes are encrypted and signed
@DynamoDBAttribute(attributeName="Description")
// Partition keys are signed but not encrypted
@DynamoDBHashKey(attributeName="Title")
// Sort keys are signed but not encrypted
@DynamoDBRangeKey(attributeName="Author")
```
예외를 지정하려면 DynamoDB Encryption Client for Java에 정의된 암호화 주석을 사용합니다. 클래스 수준에서 지정하면 해당 값이 클래스의 기본값이 됩니다.
```
// Sign only
@DoNotEncrypt
// Do nothing; not encrypted or signed
@DoNotTouch
```
예를 들어 이러한 주석은 `PublicationYear` 속성에 서명하지만 암호화하지는 않으며 `ISBN` 속성 값을 암호화하거나 서명하지 않습니다.
```
// Sign only (override the default)
@DoNotEncrypt
@DynamoDBAttribute(attributeName="PublicationYear")
// Do nothing (override the default)
@DoNotTouch
@DynamoDBAttribute(attributeName="ISBN")
```
### DynamoDBEncryptor에 대한 속성 작업
[DynamoDBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html)를 직접 사용하는 경우 속성 작업을 지정하려면 이름-값 페어가 속성 이름 및 지정한 작업을 표현하는 `HashMap` 객체를 만듭니다.
속성 작업에 유효한 값은 `EncryptionFlags` 열거 유형으로 정의되어 있습니다. `ENCRYPT` 및 `SIGN`와 함께 사용하거나 `SIGN` 단독으로 사용하거나 둘 다 생략할 수 있습니다. 하지만 `ENCRYPT` 단독으로 사용하는 경우 DynamoDB Encryption Client에서 오류가 발생합니다. 서명하지 않은 속성은 암호화할 수 없습니다.
```
ENCRYPT
SIGN
```
**주의**
기본 키 속성은 암호화하지 마십시오. 일반 텍스트로 남겨 두어야 DynamoDB에서 전체 테이블 스캔을 실행하지 않고 해당 항목을 찾을 수 있습니다.
암호화 컨텍스트에서 프라이머리 키를 지정하고 나서 프라이머리 키 속성에 대한 속성 작업에서 `ENCRYPT`를 지정하는 경우 DynamoDB Encryption Client에서 예외가 발생합니다.
예를 들어 다음 Java 코드는 `record` 항목의 모든 속성을 암호화하고 서명하는 `actions` HashMap을 만듭니다. 서명되었지만 암호화되지 않은 파티션 키 및 정렬 키 속성 및 서명되거나 암호화되지 않은 `test` 속성은 예외입니다.
```
final EnumSet signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map> actions = new HashMap<>();
for (final String attributeName : record.keySet()) {
switch (attributeName) {
case partitionKeyName: // no break; falls through to next case
case sortKeyName:
// Partition and sort keys must not be encrypted, but should be signed
actions.put(attributeName, signOnly);
break;
case "test":
// Don't encrypt or sign
break;
default:
// Encrypt and sign everything else
actions.put(attributeName, encryptAndSign);
break;
}
}
```
그런 다음 `DynamoDBEncryptor`의 [encryptRecord](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html#encryptRecord-java.util.Map-java.util.Map-com.amazonaws.services.dynamodbv2.datamodeling.encryption.EncryptionContext-) 방법을 호출할 때 맵을 `attributeFlags` 파라미터의 값으로 지정합니다. 예를 들어, `encryptRecord`에 대한 이 호출은 `actions` 맵을 사용합니다.
```
// Encrypt the plaintext record
final Map encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);
```
## 테이블 이름 재정의
DynamoDB Encryption Client에서 DynamoDB 테이블의 이름은 암호화 및 복호화 메서드에 전달되는[ DynamoDB 암호화 컨텍스트](concepts.md#encryption-context)의 요소입니다. 테이블 항목을 암호화하거나 서명할 때 테이블 이름을 포함한 DynamoDB 암호화 컨텍스트는 암호화 텍스트에 암호로 바인딩됩니다. decrypt 방법에 전달된 DynamoDB 암호화 컨텍스트가 encrypt 방법에 전달된 DynamoDB 암호화 컨텍스트와 일치하지 않으면 복호화 작업이 실패합니다.
테이블을 백업하거나 [특정 시점으로 복구](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery.html)를 수행할 때와 같이 테이블 이름이 변경되는 경우도 있습니다. 이러한 항목의 서명을 복호화하거나 확인할 때 원래 테이블 이름을 포함하여 항목을 암호화하고 서명하는 데 사용된 것과 동일한 DynamoDB 암호화 컨텍스트를 전달해야 합니다. 현재 테이블 이름은 필요하지 않습니다.
`DynamoDBEncryptor`를 사용하는 경우 DynamoDB 암호화 컨텍스트를 수동으로 결합합니다. 그러나 `DynamoDBMapper`를 사용하는 경우 `AttributeEncryptor`는 현재 테이블 이름을 포함하여 DynamoDB 암호화 컨텍스트를 만듭니다. `AttributeEncryptor`에서 다른 테이블 이름으로 암호화 컨텍스트를 만들도록 지정하려면 `EncryptionContextOverrideOperator`를 사용합니다.
예를 들어 다음 코드에서는 CMP(암호화 자료 공급자) 및 `DynamoDBEncryptor`의 인스턴스를 만듭니다. 그런 다음 `DynamoDBEncryptor`의 `setEncryptionContextOverrideOperator` 메서드를 호출합니다. 하나의 테이블 이름을 재정의하는 `overrideEncryptionContextTableName` 연산자를 사용합니다. 이 방법으로 구성되면 `AttributeEncryptor`는 `oldTableName` 대신 `newTableName`을 포함하는 DynamoDB 암호화 컨텍스트를 생성합니다. 전체 예제는 [EncryptionContextOverridesWithDynamoDBMapper.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/EncryptionContextOverridesWithDynamoDBMapper.java)를 참조하십시오.
```
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);
encryptor.setEncryptionContextOverrideOperator(EncryptionContextOperators.overrideEncryptionContextTableName(
oldTableName, newTableName));
```
항목을 복호화하고 확인하는 `DynamoDBMapper`의 load 메서드를 호출할 때 원래 테이블 이름을 지정합니다.
```
mapper.load(itemClass, DynamoDBMapperConfig.builder()
.withTableNameOverride(DynamoDBMapperConfig.TableNameOverride.withTableNameReplacement(oldTableName))
.build());
```
여러 테이블 이름을 재정의하는 `overrideEncryptionContextTableNameUsingMap` 연산자를 사용할 수도 있습니다.
테이블 이름 재정의 연산자는 일반적으로 데이터를 복호화하고 서명을 확인할 때 사용됩니다. 그러나 암호화 및 서명 시 DynamoDB 암호화 컨텍스트의 테이블 이름을 다른 값으로 설정하는 데 사용할 수 있습니다.
`DynamoDBEncryptor`를 사용하는 경우 테이블 이름 재정의 연산자를 사용하지 마십시오. 대신 원래 테이블 이름으로 암호화 컨텍스트를 만들고 복호화 메서드에 제출하십시오.
# DynamoDB Encryption Client for Java의 예제 코드
**참고**
클라이언트측 암호화 라이브러리의 [이름이 AWS Database Encryption SDK로 변경되었습니다](DDBEC-rename.md). 다음 주제에서는 Java용 DynamoDB Encryption Client 버전 1.*x*\$12.*x* 와 Python용 DynamoDB Encryption Client 버전 1.*x*\$13.*x*에 대한 정보를 제공합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB 버전 지원](legacy-dynamodb-encryption-client.md#legacy-support)을 참조하세요.
다음 예제에서는 DynamoDB Encryption Client for Java를 사용하여 애플리케이션에서 DynamoDB 테이블 항목을 보호하는 방법을 보여줍니다. GitHub의 [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/) 리포지토리의 [예제](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) 디렉터리에서 더 많은 예제를 찾고 직접 제공할 수 있습니다.
**Topics**
+ [DynamoDBEncryptor 사용](#java-example-ddb-encryptor)
+ [DynamoDBMapper 사용](#java-example-dynamodb-mapper)
## DynamoDBEncryptor 사용
이 예제에서는 [Direct KMS Provider](direct-kms-provider.md)와 함께 하위 수준 [DynamoDBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html)를 사용하는 방법을 보여줍니다. 다이렉트 KMS 공급자는 사용자가 지정한 [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) in AWS Key Management Service (AWS KMS)에서 암호화 자료를 생성하고 보호합니다.
`DynamoDBEncryptor`와 함께 호환 가능한 [암호화 자료 공급자](DDBEC-legacy-concepts.md#concept-material-provider)(CMP)를 사용할 수 있고 `DynamoDBMapper` 및 [AttributeEncryptor](java-using.md#attribute-encryptor)에서는 Direct KMS Provider를 사용할 수 있습니다.
**전체 코드 샘플 보기**: [AwsKmsEncryptedItem.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedItem.java)
1단계: Direct KMS Provider 생성
지정된 리전으로 AWS KMS 클라이언트의 인스턴스를 생성합니다. 그런 다음 클라이언트 인스턴스를 사용하여 원하는 AWS KMS key로 Direct KMS Provider의 인스턴스를 생성합니다.
이 예제에서는 Amazon 리소스 이름(ARN)을 사용하여를 식별 AWS KMS key하지만 [유효한 키 식별자를](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn) 사용할 수 있습니다.
```
final String keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
final String region = "us-west-2";
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```
2단계: 항목 생성
이 예제는 샘플 테이블 항목을 나타내는 `record` HashMap을 정의합니다.
```
final String partitionKeyName = "partition_attribute";
final String sortKeyName = "sort_attribute";
final Map record = new HashMap<>();
record.put(partitionKeyName, new AttributeValue().withS("value1"));
record.put(sortKeyName, new AttributeValue().withN("55"));
record.put("example", new AttributeValue().withS("data"));
record.put("numbers", new AttributeValue().withN("99"));
record.put("binary", new AttributeValue().withB(ByteBuffer.wrap(new byte[]{0x00, 0x01, 0x02})));
record.put("test", new AttributeValue().withS("test-value"));
```
3단계: DynamoDBEncryptor 생성
Direct KMS Provider를 사용하여 `DynamoDBEncryptor` 인스턴스를 생성합니다.
```
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);
```
4단계: DynamoDB 암호화 컨텍스트 생성
[DynamoDB 암호화 컨텍스트](concepts.md#encryption-context)에는 테이블 구조와 암호화 및 서명 방법에 대한 정보가 포함되어 있습니다. `DynamoDBMapper`를 사용하는 경우 `AttributeEncryptor`에서 자동으로 암호화 컨텍스트를 생성합니다.
```
final String tableName = "testTable";
final EncryptionContext encryptionContext = new EncryptionContext.Builder()
.withTableName(tableName)
.withHashKeyName(partitionKeyName)
.withRangeKeyName(sortKeyName)
.build();
```
5단계: 속성 작업 객체 생성
[속성 작업](DDBEC-legacy-concepts.md#legacy-attribute-actions)은 암호화 및 서명되는 항목 속성, 서명되기만 하는 속성, 암호화 및 서명되지 않는 속성을 결정합니다.
Java에서 속성 작업을 지정하려면 속성 이름 및 `EncryptionFlags` 값 페어로 구성된 HashMap을 생성합니다.
예를 들어, 다음 Java 코드는 서명되었지만 암호화되지 않은 파티션 키 및 정렬 키 속성과 서명되거나 암호화되지 않은 `test` 속성을 제외한 `record` 항목의 모든 속성을 암호화하고 서명하는 `actions` HashMap을 생성합니다.
```
final EnumSet signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map> actions = new HashMap<>();
for (final String attributeName : record.keySet()) {
switch (attributeName) {
case partitionKeyName: // fall through to the next case
case sortKeyName:
// Partition and sort keys must not be encrypted, but should be signed
actions.put(attributeName, signOnly);
break;
case "test":
// Neither encrypted nor signed
break;
default:
// Encrypt and sign all other attributes
actions.put(attributeName, encryptAndSign);
break;
}
}
```
6단계: 항목 암호화 및 서명
테이블 항목을 암호화하고 서명하려면 `DynamoDBEncryptor`의 인스턴스에서 `encryptRecord` 방법을 호출합니다. 테이블 항목(`record`), 속성 작업(`actions`) 및 암호화 컨텍스트(`encryptionContext`)를 지정합니다.
```
final Map encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);
```
7단계: DynamoDB 테이블에 항목 넣기
마지막으로 암호화되고 서명된 항목을 DynamoDB 테이블에 넣습니다.
```
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
ddb.putItem(tableName, encrypted_record);
```
## DynamoDBMapper 사용
다음 예에서는 [Direct KMS Provider](direct-kms-provider.md)와 함께 DynamoDB 매퍼 도우미 클래스를 사용하는 방법을 보여줍니다. Direct KMS Provider는 사용자가 지정한 AWS Key Management Service (AWS KMS)의 [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)로 암호화 자료를 생성 및 보호합니다.
`DynamoDBMapper`와 함께 호환 가능한 [암호화 자료 공급자](DDBEC-legacy-concepts.md#concept-material-provider)(CMP)를 사용할 수 있으며, 하위 수준 `DynamoDBEncryptor`오 함께 Direct KMS Provider를 사용할 수 있습니다.
**전체 코드 샘플 보기**: [AwsKmsEncryptedObject.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedObject.java)
1단계: Direct KMS Provider 생성
지정된 리전으로 AWS KMS 클라이언트의 인스턴스를 생성합니다. 그런 다음 클라이언트 인스턴스를 사용하여 원하는 AWS KMS key로 Direct KMS Provider의 인스턴스를 생성합니다.
이 예제에서는 Amazon 리소스 이름(ARN)을 사용하여를 식별 AWS KMS key하지만 [유효한 키 식별자를](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) 사용할 수 있습니다.
```
final String keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
final String region = "us-west-2";
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```
2단계: DynamoDB Encryptor 및 DynamoDBMapper 만들기
이전 단계에서 생성한 Direct KMS Provider를 사용하여 [DynamoDB Encryptor](java-using.md#attribute-encryptor)의 인스턴스를 생성합니다. DynamoDB Mapper를 사용하려면 하위 수준의 DynamoDB Encryptor를 인스턴스화해야 합니다.
그런 다음 DynamoDB 데이터베이스 인스턴스와 매퍼 구성을 만들고 이를 사용하여 DynamoDB Mapper의 인스턴스를 만듭니다.
`DynamoDBMapper`를 사용하여 서명된(또는 암호화 및 서명된) 항목을 추가하거나 편집하는 경우 다음 예와 같이 모든 속성을 포함하는 `PUT`와 같은 [저장 동작을 사용](java-using.md#save-behavior)하도록 구성합니다. 그렇지 않으면 데이터를 복호화하지 못할 수 있습니다.
```
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp)
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard().withRegion(region).build();
DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.PUT).build();
DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));
```
3단계: DynamoDB 테이블 정의
다음으로 DynamoDB 테이블을 정의합니다. 주석을 사용하여 [속성 작업](java-using.md#attribute-actions-java)을 지정합니다. 이 예제에서는 DynamoDB 테이블, `ExampleTable` 및 테이블 항목을 나타내는 `DataPoJo` 클래스를 만듭니다.
이 샘플 테이블에서는 기본 키 속성이 서명되지만 암호화되지는 않습니다. 이는 `@DynamoDBHashKey` 주석이 달린 `partition_attribute` 및 `@DynamoDBRangeKey` 주석이 달린 `sort_attribute`에 적용됩니다.
`@DynamoDBAttribute` 주석이 달린 속성(예: `some numbers`)은 암호화 및 서명됩니다. DynamoDB Encryption Client에서 정의한 `@DoNotEncrypt`(기호만 해당) 또는 `@DoNotTouch`(암호화 또는 서명 안 함) 암호화 주석을 사용하는 속성은 예외입니다. 예를 들어 `leave me` 속성에 `@DoNotTouch` 주석이 있으므로 암호화되거나 서명되지 않습니다.
```
@DynamoDBTable(tableName = "ExampleTable")
public static final class DataPoJo {
private String partitionAttribute;
private int sortAttribute;
private String example;
private long someNumbers;
private byte[] someBinary;
private String leaveMe;
@DynamoDBHashKey(attributeName = "partition_attribute")
public String getPartitionAttribute() {
return partitionAttribute;
}
public void setPartitionAttribute(String partitionAttribute) {
this.partitionAttribute = partitionAttribute;
}
@DynamoDBRangeKey(attributeName = "sort_attribute")
public int getSortAttribute() {
return sortAttribute;
}
public void setSortAttribute(int sortAttribute) {
this.sortAttribute = sortAttribute;
}
@DynamoDBAttribute(attributeName = "example")
public String getExample() {
return example;
}
public void setExample(String example) {
this.example = example;
}
@DynamoDBAttribute(attributeName = "some numbers")
public long getSomeNumbers() {
return someNumbers;
}
public void setSomeNumbers(long someNumbers) {
this.someNumbers = someNumbers;
}
@DynamoDBAttribute(attributeName = "and some binary")
public byte[] getSomeBinary() {
return someBinary;
}
public void setSomeBinary(byte[] someBinary) {
this.someBinary = someBinary;
}
@DynamoDBAttribute(attributeName = "leave me")
@DoNotTouch
public String getLeaveMe() {
return leaveMe;
}
public void setLeaveMe(String leaveMe) {
this.leaveMe = leaveMe;
}
@Override
public String toString() {
return "DataPoJo [partitionAttribute=" + partitionAttribute + ", sortAttribute="
+ sortAttribute + ", example=" + example + ", someNumbers=" + someNumbers
+ ", someBinary=" + Arrays.toString(someBinary) + ", leaveMe=" + leaveMe + "]";
}
}
```
4단계: 테이블 항목 암호화 및 저장
이제 테이블 항목을 만들고 DynamoDB Mapper를 사용하여 저장하면 항목이 테이블에 추가되기 전에 자동으로 암호화되고 서명됩니다.
이 예제에서는 `record`라는 테이블 항목을 정의합니다. 테이블에 저장되기 전에 해당 속성은 `DataPoJo` 클래스의 주석을 기반으로 암호화되고 서명됩니다. 이 경우 `PartitionAttribute`, `SortAttribute` 및 `LeaveMe`를 제외한 모든 속성은 암호화되고 서명됩니다. `PartitionAttribute` 및 `SortAttributes`는 서명만 됩니다. `LeaveMe` 속성은 암호화되거나 서명되지 않습니다.
`record` 항목을 암호화하고 서명한 다음 `ExampleTable`에 추가하려면 `DynamoDBMapper` 클래스의 `save` 메서드를 호출합니다. DynamoDB Mapper는 `PUT` 저장 동작을 사용하도록 구성되어 있으므로 항목을 업데이트하는 대신에 동일한 프라이머리 키로 항목을 대체합니다. 이렇게 하면 서명이 일치하고 테이블에서 항목을 가져올 때 해당 항목의 암호를 복호화할 수 있습니다.
```
DataPoJo record = new DataPoJo();
record.setPartitionAttribute("is this");
record.setSortAttribute(55);
record.setExample("data");
record.setSomeNumbers(99);
record.setSomeBinary(new byte[]{0x00, 0x01, 0x02});
record.setLeaveMe("alone");
mapper.save(record);
```
# DynamoDB Encryption Client for Python
**참고**
클라이언트측 암호화 라이브러리의 [이름이 AWS Database Encryption SDK로 변경되었습니다](DDBEC-rename.md). 다음 주제에서는 Java용 DynamoDB Encryption Client 버전 1.*x*\$12.*x* 와 Python용 DynamoDB Encryption Client 버전 1.*x*\$13.*x*에 대한 정보를 제공합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB 버전 지원](legacy-dynamodb-encryption-client.md#legacy-support)을 참조하세요.
이 주제에서는 DynamoDB Encryption Client for Pytho를 설치하고 사용하는 방법을 설명합니다. 시작하는 데 도움이 되는 전체 및 테스트된 [샘플 코드](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples)를 포함하여 GitHub의 [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/) 리포지토리에서 코드를 찾을 수 있습니다.
**참고**
DynamoDB Encryption Client for Python의 버전 1.*x*.*x* 및 2.*x*.*x*는 2022년 7월부터 [지원 종료 단계](what-is-database-encryption-sdk.md#support)에 있습니다. 가능한 한 빨리 최신 버전으로 업그레이드하세요.
**Topics**
+ [사전 조건](#python-prerequisites)
+ [설치](#python-installation)
+ [DynamoDB Encryption Client for Python 사용](python-using.md)
+ [Python 예제](python-examples.md)
## 사전 조건
Amazon DynamoDB Encryption Client for Python를 설치하기 전에 다음 사전 조건이 충족되었는지 확인합니다.
**지원되는 Python 버전**
Amazon DynamoDB Encryption Client for Python 버전 3.3.0 이상에는 Python 3.8 이상이 필요합니다. Python을 다운로드하려면 [Python 다운로드](https://www.python.org/downloads/)를 참조하세요.
이전 버전의 Amazon DynamoDB Encryption Client for Python는 Python 2.7 및 Python 3.4 이상을 지원하지만 최신 버전의 DynamoDB Encryption Client를 사용하는 것이 좋습니다.
**Python용 pip 설치 도구**
Python 3.6 이상에는 **pip**가 포함되어 있지만 업그레이드가 필요할 수도 있습니다. pip 업그레이드 또는 설치에 대한 자세한 내용은 **pip** 설명서의 [설치](https://pip.pypa.io/en/latest/installation/)를 참조하세요.
## 설치
다음 예제와 같이 **pip**를 사용하여 Amazon DynamoDB Encryption Client for Python를 설치합니다.
**최신 버전 설치**
```
pip install dynamodb-encryption-sdk
```
**pip**를 사용하여 패키지를 설치 및 업그레이드하는 방법에 대한 자세한 내용은 [패키지 설치](https://packaging.python.org/tutorials/installing-packages/)를 참조하십시오.
DynamoDB Encryption Client에는 모든 플랫폼에 [암호화 라이브러리](https://cryptography.io/en/latest/)가 필요합니다. 모든 버전의 **pip**는 Windows에 **암호화** 라이브러리를 설치하고 빌드합니다. **pip** 8.1 이상은 Linux에 **암호화**를 설치하고 구축합니다. 이전 버전의 **pip**를 사용 중이고 Linux 환경에 **암호**화 라이브러리를 빌드하는 데 필요한 도구가 없는 경우 해당 도구를 설치해야 합니다. 자세한 내용은 [Linux에서 암호화 빌드](https://cryptography.io/en/latest/installation/#building-cryptography-on-linux)를 참조하세요.
GitHub의 [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/) 리포지토리에서 DynamoDB Encryption Client의 최신 개발 버전을 얻을 수 있습니다.
DynamoDB Encryption Client를 설치한 후 이 가이드의 Python 코드 예제를 살펴보고 시작하세요.
# DynamoDB Encryption Client for Python 사용
**참고**
클라이언트측 암호화 라이브러리의 [이름이 AWS Database Encryption SDK로 변경되었습니다](DDBEC-rename.md). 다음 주제에서는 Java용 DynamoDB Encryption Client 버전 1.*x*\$12.*x* 와 Python용 DynamoDB Encryption Client 버전 1.*x*\$13.*x*에 대한 정보를 제공합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB 버전 지원](legacy-dynamodb-encryption-client.md#legacy-support)을 참조하세요.
이 주제에서는 다른 프로그래밍 언어 구현에서는 찾을 수 없는 DynamoDB Encryption Client for Python의 일부 기능에 대해 설명합니다. 이러한 기능은 가장 안전한 방법으로 DynamoDB Encryption Client를 더 쉽게 사용할 수 있도록 설계되었습니다. 특별한 사용 사례가 아니라면 이를 사용하는 것이 좋습니다.
DynamoDB Encryption Client를 사용한 프로그래밍에 대한 자세한 내용은 이 가이드의 [Python 예제](python-examples.md), GitHub의 ws-dynamodb-encryption-pytho 리포지토리의 [예제](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) 및 DynamoDB Encryption Client에 대한 [Python 설명서](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/)를 참조하세요.
**Topics**
+ [클라이언트 헬퍼 클래스](#python-helpers)
+ [TableInfo 클래스](#table-info)
+ [Python의 속성 작업](#python-attribute-actions)
## 클라이언트 헬퍼 클래스
DynamoDB Encryption Client for Python에는 DynamoDB용 Boto 3 클래스를 미러링하는 여러 클라이언트 헬퍼 클래스가 포함되어 있습니다. 이러한 헬퍼 클래스는 다음과 같이 기존 DynamoDB 애플리케이션에 암호화 및 서명을 더 쉽게 추가하고 가장 일반적인 문제를 방지할 수 있도록 설계되었습니다.
+ 기본 키에 대한 재정의 작업을 [AttributeActions](#python-attribute-actions) 객체에 추가하거나 `AttributeActions` 객체가 기본 키를 암호화하도록 클라이언트에 명시적으로 지시하는 경우 예외를 발생시키는 방식으로 항목에서 기본 키를 암호화하지 못하도록 합니다. `AttributeActions` 객체의 기본 작업이 `DO_NOTHING`이면 클라이언트 헬퍼 클래스는 프라이머리 키에 대해 해당 작업을 사용합니다. 그렇지 않으면 `SIGN_ONLY`를 사용합니다.
+ [TableInfo 객체](#python-helpers)를 생성하고 DynamoDB 호출을 기반으로 [DynamoDB 암호화 컨텍스트](concepts.md#encryption-context)를 채웁니다. 이는 DynamoDB 암호화 컨텍스트가 정확하고 클라이언트가 프라이머리 키를 식별할 수 있도록 하는 데 도움이 됩니다.
+ 테이블에 쓰거나 읽어올 때 사용자 모르게 테이블 항목을 암호화 및 복호화하는 `put_item` 및 `get_item`와 같은 방법을 지원합니다. `update_item` 메소드만 지원되지 않습니다.
하위 수준의 [항목 암호화 도구](DDBEC-legacy-concepts.md#item-encryptor)를 사용하여 직접 상호 작용하는 대신에 클라이언트 헬퍼 클래스를 사용할 수 있습니다. 항목 암호화 도구에서 고급 옵션을 설정해야 하는 경우가 아니면 이 클래스를 사용합니다.
클라이언트 헬퍼 클래스에는 다음이 포함됩니다.
+ DynamoDB의 [테이블](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table) 리소스를 사용하여 한 번에 하나의 테이블을 처리하는 애플리케이션을 위한 [EncryptedTable](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/table.html#module-dynamodb_encryption_sdk.encrypted.table).
+ 일괄 처리를 위해 DynamoDB의 [서비스 리소스](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#service-resource) 클래스를 사용하는 애플리케이션을 위한 [EncryptedResource](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/resource.html).
+ DynamoDB에서 [하위 수준 클라이언트](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#client)를 사용하는 애플리케이션을 위한 [EncryptedClient](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/client.html).
클라이언트 헬퍼 클래스를 사용하려면 호출자에게 대상 테이블에서 DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) 작업을 호출할 수 있는 권한이 있어야 합니다.
## TableInfo 클래스
[TableInfo](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/tools/structures.html#dynamodb_encryption_sdk.structures.TableInfo) 클래스는 프라이머리 키 및 보조 인덱스에 대한 필드가 포함된 DynamoDB 테이블을 나타내는 헬퍼 클래스입니다. 테이블에 대한 정확한 실시간 정보를 얻는 데 도움이 됩니다.
[클라이언트 헬퍼 클래스](#python-helpers)를 사용하는 경우 이 클래스에서 사용자를 대신하여 `TableInfo` 객체를 만들고 사용합니다. 그렇지 않으면 명시적으로 생성할 수 있습니다. 예제는 [항목 암호화 도구 사용](python-examples.md#python-example-item-encryptor) 섹션을 참조하세요.
`TableInfo` 객체에 대해 `refresh_indexed_attributes` 방법을 호출하면 DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) 작업을 호출하여 객체의 속성 값이 채워집니다. 테이블 쿼리는 하드 코딩된 인덱스 이름보다 훨씬 더 안정적입니다. `TableInfo` 클래스에는 [DynamoDB 암호화 컨텍스트](concepts.md#encryption-context)에 필요한 값을 제공하는 `encryption_context_values` 속성도 포함되어 있습니다.
`refresh_indexed_attributes` 방법을 사용하려면 호출자에게 대상 테이블에서 DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) 작업을 호출할 수 있는 권한이 있어야 합니다.
## Python의 속성 작업
[속성 작업](DDBEC-legacy-concepts.md#legacy-attribute-actions)은 항목의 각 속성에 대해 수행할 작업을 항목 암호화 도구에 알려줍니다. Python에서 속성 작업을 지정하려면 기본 작업과 특정 속성에 대한 예외가 포함된 `AttributeActions` 객체를 만듭니다. 유효한 값은 `CryptoAction` 열거 유형에 정의됩니다.
**중요**
속성 작업을 사용하여 테이블 항목을 암호화한 후 데이터 모델에서 속성을 추가하거나 제거하면 서명 검증 오류가 발생하여 데이터를 복호화하지 못할 수 있습니다. 자세한 내용은 [데이터 모델 변경](data-model.md) 단원을 참조하십시오.
```
DO_NOTHING = 0
SIGN_ONLY = 1
ENCRYPT_AND_SIGN = 2
```
예를 들어, 이 `AttributeActions` 객체는 모든 속성에 대한 기본값을 `ENCRYPT_AND_SIGN`으로 설정하고 `ISBN` 및 `PublicationYear` 속성에 대한 예외를 지정합니다.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={
'ISBN': CryptoAction.DO_NOTHING,
'PublicationYear': CryptoAction.SIGN_ONLY
}
)
```
[클라이언트 헬퍼 클래스](#python-helpers)를 사용하는 경우 기본 키 속성에 대한 속성 작업을 지정할 필요가 없습니다. 클라이언트 헬퍼 클래스는 프라이머리 키를 암호화하는 것을 방지합니다.
클라이언트 헬퍼 클래스를 사용하지 않고 프라이머리 작업이`ENCRYPT_AND_SIGN` 인 경우 프라이머리 키에 대한 작업을 지정해야 합니다. 프라이머리 키에 대한 권장 조치는 `SIGN_ONLY`입니다. 이를 쉽게 하려면 프라이머리 키에 SIGN\$1ONLY를 사용하거나 기본 작업인 경우 DO\$1NOTHING을 사용하는 `set_index_keys` 방법을 사용합니다.
**주의**
기본 키 속성은 암호화하지 마십시오. 일반 텍스트로 남겨 두어야 DynamoDB에서 전체 테이블 스캔을 실행하지 않고 해당 항목을 찾을 수 있습니다.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
)
actions.set_index_keys(*table_info.protected_index_keys())
```
# DynamoDB Encryption Client for Python의 예제 코드
**참고**
클라이언트측 암호화 라이브러리의 [이름이 AWS Database Encryption SDK로 변경되었습니다](DDBEC-rename.md). 다음 주제에서는 Java용 DynamoDB Encryption Client 버전 1.*x*\$12.*x* 와 Python용 DynamoDB Encryption Client 버전 1.*x*\$13.*x*에 대한 정보를 제공합니다. 자세한 내용은 [AWS Database Encryption SDK for DynamoDB 버전 지원](legacy-dynamodb-encryption-client.md#legacy-support)을 참조하세요.
다음 예제에서는 DynamoDB Encryption Client for Python를 사용하여 애플리케이션에서 DynamoDB 데이터를 보호하는 방법을 보여줍니다. GitHub에 있는 [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/) 리포지토리의 [예제](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) 디렉터리에서 더 많은 예제를 찾고 직접 기여할 수 있습니다.
**Topics**
+ [EncryptedTable 클라이언트 헬퍼 클래스 사용](#python-example-table)
+ [항목 암호화 도구 사용](#python-example-item-encryptor)
## EncryptedTable 클라이언트 헬퍼 클래스 사용
다음 예제에서는 [Direct KMS Provider](direct-kms-provider.md)를 `EncryptedTable` [클라이언트 헬퍼 클래스](python-using.md#python-helpers)와 함께 사용하는 방법을 보여줍니다. 이 예제에서는 다음 [항목 암호화 도구 사용](#python-example-item-encryptor) 예제와 동일한 [암호화 자료 공급자](DDBEC-legacy-concepts.md#concept-material-provider)를 사용합니다. 그러나 하위 수준 [항목 암호화 도구](DDBEC-legacy-concepts.md#item-encryptor)와 직접 상호 작용하는 대신 `EncryptedTable` 클래스를 사용합니다.
이러한 예제를 비교하면 클라이언트 도우미 클래스가 수행하는 작업을 확인할 수 있습니다. 여기에는 [DynamoDB 암호화 컨텍스트](concepts.md#encryption-context)를 생성하거나 프라이머리 키 속성을 항상 서명하되 절대로 암호화되지 않은 상태로 유지하는 등의 작업이 포함됩니다. 암호화 컨텍스트를 만들고 프라이머리 키를 검색하기 위해 클라이언트 헬퍼 클래스는 DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) 작업을 호출합니다. 이 코드를 실행하려면 이 작업을 호출할 수 있는 권한이 있어야 합니다.
**전체 코드 샘플 보기**: [aws\$1kms\$1encrypted\$1table.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py)
1단계: 테이블 만들기
테이블 이름을 사용하여 표준 DynamoDB 테이블의 인스턴스를 생성하는 것부터 시작합니다.
```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```
2단계: 암호화 자료 공급자 생성
선택한 [암호화 자료 공급자](crypto-materials-providers.md)(CMP)의 인스턴스를 생성합니다.
이 예제에서는 [Direct KMS Provider](direct-kms-provider.md)를 사용하지만, 사용자는 모든 호환되는 CMP를 사용할 수 있습니다. Direct KMS Provider를 생성하려면 [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)를 지정합니다. 이 예제에서는의 Amazon 리소스 이름(ARN)을 사용하지 AWS KMS key만 유효한 키 식별자를 사용할 수 있습니다.
```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```
3단계: 속성 작업 객체 생성
[속성 작업](DDBEC-legacy-concepts.md#legacy-attribute-actions)은 항목의 각 속성에 대해 수행할 작업을 항목 암호화 도구에 알려줍니다. 이 예제의 `AttributeActions` 객체는 무시되는 `test` 속성을 제외한 모든 항목을 암호화하고 서명합니다.
클라이언트 도우미 클래스를 사용할 때 프라이머리 키 속성에 대한 속성 작업을 지정하지 않습니다. `EncryptedTable` 클래스는 프라이머리 키 속성을 서명하지만 암호화하지는 않습니다.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={'test': CryptoAction.DO_NOTHING}
)
```
4단계: 암호화된 테이블 생성
표준 테이블, Direct KMS Provider 및 속성 작업을 사용하여 암호화된 테이블을 생성합니다. 이 단계로 구성이 완료됩니다.
```
encrypted_table = EncryptedTable(
table=table,
materials_provider=kms_cmp,
attribute_actions=actions
)
```
5단계: 테이블에 일반 텍스트 항목 넣기
`encrypted_table`에 대한 `put_item` 방법을 호출하면 테이블 항목이 투명하게 암호화되고 서명되어 DynamoDB 테이블에 추가됩니다.
먼저 테이블 항목을 정의합니다.
```
plaintext_item = {
'partition_attribute': 'value1',
'sort_attribute': 55
'example': 'data',
'numbers': 99,
'binary': Binary(b'\x00\x01\x02'),
'test': 'test-value'
}
```
그런 다음 테이블에 넣습니다.
```
encrypted_table.put_item(Item=plaintext_item)
```
암호화된 형식으로 DynamoDB 테이블에서 항목을 가져오려면 `table` 객체에 대한 `get_item` 방법을 호출합니다. 복호화된 항목을 얻으려면 `encrypted_table` 객체에 대한 `get_item` 메서드를 호출합니다.
## 항목 암호화 도구 사용
이 예제에서는 테이블 항목을 암호화할 때 항목 암호화 도구와 상호 작용하는 [클라이언트 헬퍼 클래스](python-using.md#python-helpers)를 사용하는 대신 DynamoDB Encryption Client의 [항목 암호화 도구](DDBEC-legacy-concepts.md#item-encryptor)와 직접 상호 작용하는 방법을 보여줍니다.
이 기술을 사용하면 DynamoDB 암호화 컨텍스트와 구성 객체(`CryptoConfig`)를 수동으로 생성합니다. 또한 한 번의 호출로 항목을 암호화하고 별도의 호출로 DynamoDB 테이블에 넣습니다. 이를 통해 `put_item` 호출을 사용자 지정하고 DynamoDB Encryption Client를 사용하여 DynamoDB로 전송되지 않는 구조화된 데이터를 암호화하고 서명할 수 있습니다.
이 예제에서는 [Direct KMS Provider](direct-kms-provider.md)를 사용하지만, 사용자는 모든 호환되는 CMP를 사용할 수 있습니다.
**전체 코드 샘플 보기**: [aws\$1kms\$1encrypted\$1item.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py)
1단계: 테이블 만들기
테이블 이름을 사용하여 표준 DynamoDB 테이블 리소스의 인스턴스를 생성하는 것부터 시작합니다.
```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```
2단계: 암호화 자료 공급자 생성
선택한 [암호화 자료 공급자](crypto-materials-providers.md)(CMP)의 인스턴스를 생성합니다.
이 예제에서는 [Direct KMS Provider](direct-kms-provider.md)를 사용하지만, 사용자는 모든 호환되는 CMP를 사용할 수 있습니다. Direct KMS Provider를 생성하려면 [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)를 지정합니다. 이 예제에서는의 Amazon 리소스 이름(ARN)을 사용하지 AWS KMS key만 유효한 키 식별자를 사용할 수 있습니다.
```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```
3단계: TableInfo 헬퍼 클래스 사용
DynamoDB에서 테이블에 대한 정보를 얻으려면 [TableInfo](python-using.md#python-helpers) 헬퍼 클래스의 인스턴스를 생성합니다. 항목 암호화 도구로 직접 작업하는 경우 `TableInfo` 인스턴스를 생성하고 해당 메서드를 호출해야 합니다. [클라이언트 헬퍼 클래스](python-using.md#python-helpers)가 사용자를 대신하여 이 작업을 수행합니다.
`TableInfo`의 `refresh_indexed_attributes` 메소드는 [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) DynamoDB 작업을 사용하여 테이블에 대한 정확한 정보를 실시간으로 가져옵니다. 여기에는 프라이머리 키와 로컬 및 글로벌 보조 인덱스가 포함됩니다. 호출자에게 `DescribeTable`을 호출할 수 있는 권한이 있어야 합니다.
```
table_info = TableInfo(name=table_name)
table_info.refresh_indexed_attributes(table.meta.client)
```
4단계: DynamoDB 암호화 컨텍스트 생성
[DynamoDB 암호화 컨텍스트](concepts.md#encryption-context)에는 테이블 구조와 암호화 및 서명 방법에 대한 정보가 포함되어 있습니다. 이 예제에서는 항목 암호화 도구와 상호 작용하므로 DynamoDB 암호화 컨텍스트를 명시적으로 생성합니다. [클라이언트 헬퍼 클래스](python-using.md#python-helpers)는 DynamoDB 암호화 컨텍스트를 생성합니다.
[TableInfo](python-using.md#python-helpers) 헬퍼 클래스의 속성을 사용하여 파티션 키와 정렬 키를 가져올 수 있습니다.
```
index_key = {
'partition_attribute': 'value1',
'sort_attribute': 55
}
encryption_context = EncryptionContext(
table_name=table_name,
partition_key_name=table_info.primary_index.partition,
sort_key_name=table_info.primary_index.sort,
attributes=dict_to_ddb(index_key)
)
```
5단계: 속성 작업 객체 생성
[속성 작업](DDBEC-legacy-concepts.md#legacy-attribute-actions)은 항목의 각 속성에 대해 수행할 작업을 항목 암호화 도구에 알려줍니다. 이 예제의 `AttributeActions` 객체는 서명되었지만 암호화되지 않은 프라이머리 키 속성과 무시되는 `test` 속성을 제외한 모든 항목을 암호화하고 서명합니다.
항목 암호화 도구와 직접 상호작용하고 기본 작업이 `ENCRYPT_AND_SIGN`인 경우 프라이머리 키에 대한 대체 작업을 지정해야 합니다. 프라이머리 키에 대한 `SIGN_ONLY`을 사용하거나 기본 작업인 경우 `DO_NOTHING`을 사용하는 `set_index_keys` 메서드를 사용할 수 있습니다.
프라이머리 키를 지정하기 위해 이 예제에서는 DynamoDB 호출로 채워지는 [TableInfo](python-using.md#python-helpers) 객체의 인덱스 키를 사용합니다. 이 기술은 프라이머리 키 이름을 하드 코딩하는 것보다 안전합니다.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={'test': CryptoAction.DO_NOTHING}
)
actions.set_index_keys(*table_info.protected_index_keys())
```
6단계: 항목에 대한 구성 만들기
DynamoDB Encryption Client를 구성하려면 테이블 항목에 대한 [CryptoConfig](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/config.html) 구성에서 방금 생성한 객체를 사용합니다. 클라이언트 헬퍼 클래스는 사용자를 위해 CryptoConfig를 만듭니다.
```
crypto_config = CryptoConfig(
materials_provider=kms_cmp,
encryption_context=encryption_context,
attribute_actions=actions
)
```
7단계: 항목 암호화
이 단계에서는 항목을 암호화하고 서명하지만 DynamoDB 테이블에 저장하지는 않습니다.
클라이언트 헬퍼 클래스를 사용할 경우 항목이 사용자 모르게 암호화 및 서명된 다음, 사용자가 헬퍼 클래스의 `put_item` 메서드를 호출할 때 DynamoDB 테이블에 추가됩니다. 항목 암호화 도구를 직접 사용하는 경우 암호화 및 입력 작업은 독립적입니다.
먼저 일반 텍스트 항목을 만듭니다.
```
plaintext_item = {
'partition_attribute': 'value1',
'sort_key': 55,
'example': 'data',
'numbers': 99,
'binary': Binary(b'\x00\x01\x02'),
'test': 'test-value'
}
```
그런 다음 암호화하고 서명합니다. `encrypt_python_item` 방법에는 `CryptoConfig` 구성 객체가 필요합니다.
```
encrypted_item = encrypt_python_item(plaintext_item, crypto_config)
```
8단계: 테이블에 항목 넣기
이 단계에서는 암호화되고 서명된 항목을 DynamoDB 테이블에 넣습니다.
```
table.put_item(Item=encrypted_item)
```
암호화된 항목을 보려면 `encrypted_table` 객체 대신 원본 `table` 객체에 대한 `get_item` 방법을 호출합니다. 항목을 확인 및 복호화하지 않고 DynamoDB 테이블에서 항목을 가져옵니다.
```
encrypted_item = table.get_item(Key=partition_key)['Item']
```
다음 이미지는 암호화되고 서명된 테이블 항목 예제의 일부를 보여줍니다.
암호화된 속성 값은 이진 데이터입니다. 프라이머리 키 속성(`partition_attribute` 및 `sort_attribute`)의 이름과 값 및 `test` 속성은 일반 텍스트로 유지됩니다. 이 출력은 서명(`*amzn-ddb-map-sig*`)을 포함하는 속성과 [자료 설명 속성](DDBEC-legacy-concepts.md#legacy-material-description)(`*amzn-ddb-map-desc*`)을 보여줍니다.
![\[암호화 및 서명된 항목(발췌)\]](http://docs.aws.amazon.com/ko_kr/database-encryption-sdk/latest/devguide/images/encrypted-item-closeup.png)