기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS KMS 마스터 키 공급자 업데이트
최신 1.*x* 버전의 로 마이그레이션 AWS Encryption SDK한 다음 버전 2.0.*x* 이상으로 마이그레이션하려면 레거시 AWS KMS 마스터 키 공급자를 [*엄격 모드* 또는 *검색 모드에서*](about-versions.md#changes-to-mkps) 명시적으로 생성된 마스터 키 공급자로 바꿔야 합니다. 레거시 마스터 키 공급자는 버전 1.7*x*에서 더 이상 사용되지 않으며 버전 2.0.*x*에서 제거되었습니다. 이 변경은 [AWS Encryption SDK for Java](java.md), [AWS Encryption SDK for Python](python.md) 및 [AWS Encryption CLI](crypto-cli.md)를 사용하는 애플리케이션 및 스크립트에 반드시 필요합니다. 이 섹션의 예제는 코드를 업데이트하는 방법을 보여줍니다.
**참고**
Python의 경우 [지원 중단 경고를 켭니다](https://docs.python.org/3/library/warnings.html). 이렇게 하면 코드에서 업데이트해야 하는 부분을 식별하는 데 도움이 됩니다.
AWS KMS 마스터 키(마스터 키 공급자 아님)를 사용하는 경우이 단계를 건너뛸 수 있습니다. AWS KMS 마스터 키는 더 이상 사용되지 않거나 제거되지 않습니다. 해당 마스터 키는 지정한 래핑 키로만 암호화하고 복호화합니다.
이 섹션의 예제는 변경해야 하는 코드 요소에 초점을 맞춥니다. 업데이트된 코드의 전체 예제는 해당 [프로그래밍 언어](programming-languages.md)의 GitHub 리포지토리의 예제 섹션을 참조하세요. 또한 이러한 예제에서는 일반적으로 키 ARNs 사용하여를 나타냅니다 AWS KMS keys. 암호화를 위한 마스터 키 공급자를 생성할 때 유효한 AWS KMS [키 식별자](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)를 사용하여를 나타낼 수 있습니다 AWS KMS key . 복호화를 위한 마스터 키 공급자를 생성할 경우 키 ARN을 사용해야 합니다.
**마이그레이션에 대해 자세히 알아보기**
모든 AWS Encryption SDK 사용자에 대해에서 커밋 정책을 설정하는 방법에 대해 알아봅니다[커밋 정책 설정](migrate-commitment-policy.md).
AWS Encryption SDK for C 및 AWS Encryption SDK for JavaScript 사용자의 경우의 키링에 대한 선택적 업데이트에 대해 알아봅니다[AWS KMS 키링 업데이트](migrate-keyrings-v2.md).
**Topics**
+ [엄격 모드로 마이그레이션](#migrate-mkp-strict-mode)
+ [검색 모드로 마이그레이션](#migrate-mkp-discovery-mode)
## 엄격 모드로 마이그레이션
의 최신 1.*x* 버전으로 업데이트한 후 레거시 마스터 키 공급자를 엄격 모드의 마스터 키 공급자로 AWS Encryption SDK바꿉니다. 엄격 모드에서는 암호화 및 복호화 시 사용할 래핑 키를 지정해야 합니다. 는 지정한 래핑 키만 AWS Encryption SDK 사용합니다. 더 이상 사용되지 않는 마스터 키 공급자는 및 AWS 계정 리전 AWS KMS keys 을 포함하여 데이터 키를 암호화 AWS KMS key 한를 사용하여 데이터를 해독할 수 있습니다.
엄격한 모드의 마스터 키 공급자는 AWS Encryption SDK 버전 1.7.*x*에 도입되었습니다. 이는 버전 1.7*x*에서 더 이상 사용되지 않으며 버전 2.0.*x*에서 제거되는 레거시 마스터 키 공급자를 교체합니다. 엄격 모드에서 마스터 키 공급자를 사용하는 것이 AWS Encryption SDK [ 모범 사례](best-practices.md)입니다.
다음 코드는 암호화 및 복호화에 사용할 수 있는 엄격 모드의 마스터 키 공급자를 생성합니다.
------
#### [ Java ]
이 예제는 AWS Encryption SDK for Java의 버전 1.6.2 이하 버전을 사용하는 애플리케이션의 코드를 나타냅니다.
이 코드는 `KmsMasterKeyProvider.builder()` 메서드를 사용하여 마스터 키 공급자를 래핑 키 AWS KMS key 로 사용하는 AWS KMS 마스터 키 공급자를 인스턴스화합니다.
```
// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.withKeysForEncryption(awsKmsKey)
.build();
```
이 예제는 AWS Encryption SDK for Java 의 버전 1.7.*x* 이상 버전을 사용하는 애플리케이션의 코드를 나타냅니다. 전체 예제는 [BasicEncryptionExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/BasicEncryptionExample.java)를 참조하세요.
이전 예제에서 사용된 `Builder.build()` 및 `Builder.withKeysForEncryption()` 메서드는 버전 1.7.*x*에서 더 이상 사용되지 않으며 버전 2.0.*x*에서 제거되었습니다.
엄격 모드 마스터 키 공급자로 업데이트하기 위해 이 코드는 더 이상 사용되지 않는 메서드에 대한 호출을 새 `Builder.buildStrict()` 메서드에 대한 호출로 대체합니다. 이 예제에서는 래핑 키 AWS KMS key 로 하나를 지정하지만 `Builder.buildStrict()` 메서드는 여러의 목록을 가져올 수 있습니다 AWS KMS keys.
```
// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your AWS 계정.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
```
------
#### [ Python ]
이 예제는 AWS Encryption SDK for Python의 버전 1.4.1을 사용하는 애플리케이션의 코드를 나타냅니다. 이 코드는 버전 1.7.*x*에서 더 이상 사용되지 않으며 버전 2.0.*x*에서 제거된 `KMSMasterKeyProvider`를 사용합니다. 복호화 시 AWS KMS keys 지정한에 관계없이 데이터 키를 암호화 AWS KMS key 한를 사용합니다.
단, `KMSMasterKey`는 더 이상 사용되지 않거나 제거되지 않았습니다. 암호화 및 복호화 시 AWS KMS key 지정한 만 사용합니다.
```
# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = KMSMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
이 예제는 AWS Encryption SDK for Python의 버전 1.7.*x*를 사용하는 애플리케이션의 코드를 나타냅니다. 전체 예제는 [basic\$1encryption.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/basic_encryption.py)를 참조하세요.
엄격 모드 마스터 키 공급자로 업데이트하기 위해 이 코드는 `KMSMasterKeyProvider()`에 대한 호출을 `StrictAwsKmsMasterKeyProvider()`에 대한 호출로 대체합니다.
```
# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your AWS 계정
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
------
#### [ AWS Encryption CLI ]
이 예제에서는 Encryption CLI 버전 1.1.7 이하를 사용하여 AWS 암호화 및 복호화하는 방법을 보여줍니다.
1.1.7 이하 버전에서는 암호화할 때 하나 이상의 마스터 키(또는 *래핑 키*)를 지정합니다(예: AWS KMS key). 사용자 지정 마스터 키 공급자를 사용하지 않는 한 복호화 시 래핑 키를 지정할 수 없습니다. AWS 암호화 CLI는 데이터 키를 암호화한 모든 래핑 키를 사용할 수 있습니다.
```
\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--master-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
이 예제에서는 AWS Encryption CLI 버전 1.7.*x* 이상을 사용하여 암호화 및 복호화하는 방법을 보여줍니다. 전체 예제는 [AWS 암호화 CLI의 예](crypto-cli-examples.md) 섹션을 참조하세요.
`--master-keys` 파라미터는 버전 1.7.*x*에서 더 이상 사용되지 않으며 버전 2.0.*x*에서 제거되었습니다. 암호화 및 복호화 명령에 필요한 `--wrapping-keys` 파라미터로 대체되었습니다. 이 파라미터는 엄격 모드 및 검색 모드를 지원합니다. 엄격한 모드는 의도한 래핑 키를 사용하도록 보장하는 AWS Encryption SDK 모범 사례입니다.
*엄격 모드*로 업그레이드하려면 `--wrapping-keys` 파라미터의 **key** 속성을 사용하여 암호화 및 복호화 시 래핑 키를 지정하세요.
```
\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
## 검색 모드로 마이그레이션
버전 1.7.*x*부터 마스터 키 공급자에 대해 AWS KMS *엄격 모드를* 사용하는 것이 AWS Encryption SDK [가장 좋습니다](best-practices.md). 즉, 암호화 및 복호화 시 래핑 키를 지정하는 것입니다. 암호화할 때는 항상 래핑 키를 지정해야 합니다. 그러나 복호화를 AWS KMS keys 위해의 키 ARNs을 지정하는 것이 실용적이지 않은 경우가 있습니다. 예를 들어 별칭을 사용하여 암호화 AWS KMS keys 할 때를 식별하는 경우 복호화할 때 키 ARNs을 나열해야 하는 경우 별칭의 이점을 잃게 됩니다. 또한 검색 모드의 마스터 키 공급자는 원래 마스터 키 공급자처럼 작동하므로 마이그레이션 전략의 일환으로 일시적으로 사용하고 나중에 엄격 모드에서 마스터 키 공급자로 업그레이드할 수 있습니다.
이와 같은 경우에는 *검색 모드*에서 마스터 키 공급자를 사용할 수 있습니다. 이러한 마스터 키 공급자에서는 래핑 키를 지정할 수 없으므로 암호화에 사용할 수 없습니다. 복호화할 때는 데이터 키를 암호화한 모든 래핑 키를 사용할 수 있습니다. 하지만 동일한 방식으로 동작하는 레거시 마스터 키 공급자와는 달리 검색 모드에서 명시적으로 생성해야 합니다. 검색 모드에서 마스터 키 공급자를 사용하는 경우 사용할 수 있는 래핑 키를 특정 AWS 계정의 것으로만 제한할 수 있습니다. 이 검색 필터는 선택 사항이지만 권장되는 모범 사례입니다. AWS 파티션과 계정에 대한 자세한 내용은 *AWS 일반 참조*의 [Amazon 리소스 이름](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)을 참조하세요.
다음 예제에서는 암호화를 위한 엄격 모드의 AWS KMS 마스터 키 공급자와 복호화를 위한 검색 모드의 AWS KMS 마스터 키 공급자를 생성합니다. 검색 모드의 마스터 키 공급자는 검색 필터를 사용하여 복호화에 사용되는 래핑 키를 `aws` 파티션 및 특정 예제 AWS 계정으로만 제한합니다. 매우 간단한 이 예제에서는 계정 필터가 필요하지 않지만 한 애플리케이션에서 데이터를 암호화하고 다른 애플리케이션에서 데이터를 복호화할 때 매우 유용한 모범 사례입니다.
------
#### [ Java ]
이 예제는 AWS Encryption SDK for Java의 버전 1.7.*x* 이상 버전을 사용하는 애플리케이션의 코드를 나타냅니다. 전체 예제는 [DiscoveryDecryptionExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/)를 참조하세요.
암호화를 위한 엄격 모드에서 마스터 키 공급자를 인스턴스화하기 위해 이 예제에서는 `Builder.buildStrict()` 메서드를 사용합니다. 복호화를 위한 검색 모드에서 마스터 키 공급자를 인스턴스화하기 위해서는 `Builder.buildDiscovery()` 메서드를 사용합니다. `Builder.buildDiscovery()` 메서드는 지정된 AWS 파티션 및 계정 AWS KMS keys 에서를 AWS Encryption SDK 로 제한`DiscoveryFilter`하는를 사용합니다.
```
// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your AWS 계정.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";
KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));
KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildDiscovery(accounts);
```
------
#### [ Python ]
이 예제는 AWS Encryption SDK for Python 의 버전 1.7.*x* 이상 버전을 사용하는 애플리케이션의 코드를 나타냅니다. 전체 예제는 [discovery\$1kms\$1provider.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/discovery_kms_provider.py)를 참조하세요.
암호화를 위한 엄격 모드에서 마스터 키 공급자를 생성하기 위해 이 예제에서는 `StrictAwsKmsMasterKeyProvider`를 사용합니다. 복호화를 위한 검색 모드에서 마스터 키 공급자를 생성하기 위해 지정된 AWS 파티션 및 계정 AWS KMS keys 에서를 AWS Encryption SDK 로 제한`DiscoveryFilter`하는 `DiscoveryAwsKmsMasterKeyProvider`와 함께를 사용합니다.
```
# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your AWS 계정.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
partition="aws",
account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
discovery_filter=accounts
)
```
------
#### [ AWS Encryption CLI ]
이 예제에서는 AWS Encryption CLI 버전 1.7.*x* 이상을 사용하여 암호화 및 복호화하는 방법을 보여줍니다. 버전 1.7.*x*부터 암호화 및 복호화 시 `--wrapping-keys` 파라미터가 필요합니다. `--wrapping-keys` 파라미터는 엄격 모드 및 검색 모드를 지원합니다. 전체 예제는 [AWS 암호화 CLI의 예](crypto-cli-examples.md) 섹션을 참조하세요.
암호화할 때 이 예제에서는 래핑 키를 지정합니다(필수 사항). 복호화할 때는 값이 `true`인 `--wrapping-keys` 파라미터의 `discovery` 속성을 사용하여 *검색 모드*를 명시적으로 선택합니다.
이 검색 모드에서 사용할 AWS Encryption SDK 수 있는 래핑 키를 특히 래핑 키로 제한하기 위해 AWS 계정이 예제에서는 `--wrapping-keys` 파라미터의 `discovery-partition` 및 `discovery-account` 속성을 사용합니다. 이러한 선택적 속성은 `discovery` 속성이 `true`로 설정된 경우에만 유효합니다. `discovery-partition` 및 `discovery-account` 속성을 함께 사용해야 하며 둘 다 단독으로는 유효하지 않습니다.
```
\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyAlias \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------