기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 마이그레이션 AWS Encryption SDK
는 여러 상호 운용 가능한 [프로그래밍 언어 구현](programming-languages.md)을 AWS Encryption SDK 지원하며, 각 구현은 GitHub의 오픈 소스 리포지토리에서 개발됩니다. [가장 좋은 방법은](best-practices.md) 각 언어에 AWS Encryption SDK 대해 최신 버전의를 사용하는 것입니다.
버전 2.0.*x* 이상에서 최신 버전으로 안전하게 업그레이드 AWS Encryption SDK 할 수 있습니다. 그러나의 2.0.*x* 버전에는 중요한 새로운 보안 기능이 AWS Encryption SDK 도입되었으며, 그 중 일부는 주요 변경 사항입니다. 1.7.*x* 이하 버전에서 2.0.*x* 및 이상 버전으로 업그레이드하려면 먼저 최신 1.*x* 버전으로 업그레이드해야 합니다. 이 섹션의 항목은 변경 사항을 이해하고, 애플리케이션에 맞는 올바른 버전을 선택하고, AWS Encryption SDK의 최신 버전으로 안전하고 성공적으로 마이그레이션하는 데 도움이 되도록 설계되었습니다.
의 중요 버전에 대한 자세한 내용은 섹션을 AWS Encryption SDK참조하세요[의 버전 AWS Encryption SDK](about-versions.md).
**중요**
1.7.*x* 이하 버전에서 최신 1.*x* 버전으로 먼저 업그레이드하지 않고 곧바로 2.0.*x* 이상 버전으로 업그레이드해서는 안됩니다. 버전 2.0.*x* 이상으로 직접 업그레이드하고 모든 새 기능을 즉시 활성화하면 AWS Encryption SDK 는 이전 버전의에서 암호화된 사이퍼텍스트를 해독할 수 없습니다 AWS Encryption SDK.
**참고**
AWS Encryption SDK for .NET의 최신 버전은 버전 3.0.*x*입니다. AWS Encryption SDK for .NET의 모든 버전은의 2.0.*x*에 도입된 보안 모범 사례를 지원합니다 AWS Encryption SDK. 코드나 데이터를 변경하지 않고도 최신 버전으로 안전하게 업그레이드할 수 있습니다.
AWS Encryption CLI:이 마이그레이션 가이드를 읽을 때 AWS Encryption CLI 1.8.*x*에 대한 1.7.*x* 마이그레이션 지침을 사용하고 AWS Encryption CLI 2.1.*x*에 대한 2.0.*x* 마이그레이션 지침을 사용합니다. 자세한 내용은 [AWS 암호화 CLI 버전](crypto-cli-versions.md)을 참조하세요.
새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요.
**신규 사용자**
를 처음 사용하는 경우 프로그래밍 언어에 AWS Encryption SDK 맞는 최신 버전의를 AWS Encryption SDK설치합니다. 기본값은의 서명 AWS Encryption SDK, 키 파생 및 [키 커](concepts.md#key-commitment)밋을 사용한 암호화를 포함하여의 모든 보안 기능을 활성화합니다. AWS Encryption SDK
**현재 사용자**
가능한 한 빨리 현재 버전에서 사용 가능한 최신 버전으로 업그레이드하는 것이 좋습니다. 의 모든 1.*x* 버전 AWS Encryption SDK 은 일부 프로그래밍 언어의 이후 버전과 마찬가지로 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 사용 중인 프로그래밍 언어의 AWS Encryption SDK 지원 및 유지 관리 상태에 대한 자세한 내용은 [지원 및 유지 관리](introduction.md#support) 섹션을 참조하세요.
AWS Encryption SDK 버전 2.0.*x* 이상에서는 데이터를 보호하는 데 도움이 되는 새로운 보안 기능을 제공합니다. 그러나 AWS Encryption SDK 버전 2.0.*x*에는 이전 버전과 호환되지 않는 주요 변경 사항이 포함되어 있습니다. 안전하게 전환하려면 먼저 현재 버전에서 사용하는 프로그래밍 언어의 최신 1.*x* 버전으로 마이그레이션하세요. 최신 1.*x* 버전이 완전히 배포되고 제대로 작동하면 2.0.*x* 이상 버전으로 안전하게 마이그레이션할 수 있습니다. 이 [2단계 프로세스](migration-guide.md)는 특히 분산 애플리케이션에 중요합니다.
이러한 변경 사항의 기반이 되는 AWS Encryption SDK 보안 기능에 대한 자세한 내용은 *AWS 보안 블로그*의 [향상된 클라이언트 측 암호화: 명시적 KeyIds 및 키 커](https://aws.amazon.com/blogs/security/improved-client-side-encryption-explicit-keyids-and-key-commitment/)밋을 참조하세요.
에서를 사용하는 데 도움이 필요하신 AWS Encryption SDK for Java 가요 AWS SDK for Java 2.x? [사전 조건](java.md#java-prerequisites)을(를) 참조하세요.
**Topics**
+ [마이그레이션 및 배포 방법 AWS Encryption SDK](migration-guide.md)
+ [AWS KMS 마스터 키 공급자 업데이트](migrate-mkps-v2.md)
+ [AWS KMS 키링 업데이트](migrate-keyrings-v2.md)
+ [커밋 정책 설정](migrate-commitment-policy.md)
+ [최신 버전으로의 마이그레이션 문제 해결](troubleshooting-migration.md)
# 마이그레이션 및 배포 방법 AWS Encryption SDK
1.7.*x* 이전 AWS Encryption SDK 버전에서 버전 2.0.*x* 이상으로 마이그레이션할 때는 [키 커밋](concepts.md#key-commitment)을 사용하여 암호화로 안전하게 전환해야 합니다. 그러지 않으면 애플리케이션에서 복호화할 수 없는 사이퍼텍스트가 만들어집니다. AWS KMS 마스터 키 공급자를 사용하는 경우 엄격 모드 또는 검색 모드에서 마스터 키 공급자를 생성하는 새 생성자로 업데이트해야 합니다.
**참고**
이 항목은 AWS Encryption SDK 의 이하 버전에서 2.0.*x* 이상 버전으로 마이그레이션하는 사용자를 대상으로 합니다. 를 처음 AWS Encryption SDK사용하는 경우 기본 설정으로 사용 가능한 최신 버전을 즉시 사용할 수 있습니다.
읽어야 하는 사이퍼텍스트를 복호화할 수 없는 심각한 상황을 피하려면 여러 단계를 거쳐 마이그레이션하고 배포하는 것이 좋습니다. 다음 단계를 시작하기 전에 각 단계가 완료되고 완전히 배포되었는지 확인하세요. 이는 여러 호스트가 있는 분산 애플리케이션에 특히 중요합니다.
## 1단계: 애플리케이션을 최신 1.*x* 버전으로 업데이트합니다.
사용 중인 프로그래밍 언어의 최신 1.*x* 버전으로 업데이트합니다. 2단계를 시작하기 전에 신중하게 테스트하고 변경 내용을 배포한 다음 업데이트가 모든 대상 호스트에 전파되었는지 확인합니다.
**중요**
최신 1.*x* 버전이 AWS Encryption SDK의 1.7.*x* 또는 이상 버전인지 확인하세요.
의 최신 1.*x* 버전 AWS Encryption SDK 은의 레거시 버전 AWS Encryption SDK 과 이전 버전과 호환되며 버전 2.0.*x* 이상과 호환됩니다. 여기에는 버전 2.0.*x*에 있는 새 기능이 포함되지만 해당 마이그레이션을 위해 설계된 안전한 기본값을 포함해야 합니다. 필요한 경우 AWS KMS 마스터 키 공급자를 업그레이드하고 키 커밋으로 사이퍼텍스트를 복호화할 수 있는 알고리즘 제품군으로 완전히 배포할 수 있습니다.
+ 레거시 AWS KMS 마스터 키 제공자의 생성자를 포함하여 더 이상 사용되지 않는 요소를 교체하세요. [Python](https://docs.python.org/3/library/warnings.html)의 경우 지원 중단 경고를 켭니다. 최신 1.*x* 버전에서 더 이상 사용되지 않는 코드 요소는 2.0.*x* 이상 버전에서 제거되었습니다.
+ 커밋 정책을 `ForbidEncryptAllowDecrypt`로 명시적으로 설정합니다. 최신 1.*x* 버전에서 유일하게 유효한 값이지만 이 릴리스에 도입된 API를 사용할 때 해당 설정이 필요합니다. 버전 2.0.*x* 이상 버전으로 마이그레이션할 때 애플리케이션이 키 커밋 없이 암호화된 사이퍼텍스트를 거부하는 것을 방지합니다. 자세한 내용은 [커밋 정책 설정](migrate-commitment-policy.md)을 참조하세요.
+ AWS KMS 마스터 키 공급자를 사용하는 경우 레거시 마스터 키 공급자를 *엄격 모드* 및 *검색 모드를* 지원하는 마스터 키 공급자로 업데이트해야 합니다. 이 업데이트는 AWS Encryption SDK for Java AWS Encryption SDK for Python, 및 AWS 암호화 CLI에 필요합니다. 검색 모드에서 마스터 키 제공자를 사용하는 경우 사용되는 래핑 키를 특정 AWS 계정의 래핑 키로 제한하는 검색 필터를 구현하는 것이 좋습니다. 이 업데이트는 선택 사항이지만 권장되는 [모범 사례](best-practices.md)입니다. 자세한 내용은 [AWS KMS 마스터 키 공급자 업데이트](migrate-mkps-v2.md)을 참조하세요.
+ [AWS KMS 검색 키링](use-kms-keyring.md#kms-keyring-discovery)을 사용하는 경우 복호화에 사용되는 래핑 키를 특정 AWS 계정의 래핑 키로 제한하는 검색 필터를 구현하는 것이 좋습니다. 이 업데이트는 선택 사항이지만 권장되는 [모범 사례](best-practices.md)입니다. 자세한 내용은 [AWS KMS 키링 업데이트](migrate-keyrings-v2.md)을 참조하세요.
## 2단계: 애플리케이션을 최신 버전으로 업데이트
최신 1. *x* 버전을 모든 호스트에 배포했으면 2.0.*x* 이상 버전으로 업그레이드할 수 있습니다. 버전 2.0.*x*에는 모든 이전 버전의 주요 변경 사항이 포함되어 있습니다 AWS Encryption SDK. 하지만 1단계에서 권장하는 대로 코드를 변경하면 최신 버전으로 마이그레이션할 때 오류를 피할 수 있습니다.
최신 버전으로 업데이트하기 전에 커밋 정책이 일관되게 `ForbidEncryptAllowDecrypt`로 설정되어 있는지 확인하세요. 그런 다음 데이터 구성에 따라 편할 때에 `RequireEncryptAllowDecrypt`로 마이그레이션한 다음 기본 설정인 `RequireEncryptRequireDecrypt`로 할 수 있습니다. 다음 패턴과 같이 일련의 전환 단계를 수행하는 것이 좋습니다.
1. [커밋 정책](migrate-commitment-policy.md)을 `ForbidEncryptAllowDecrypt`로 설정한 상태에서 시작하세요. AWS Encryption SDK 는 키 커밋으로 메시지를 복호화할 수 있지만 아직 키 커밋을 사용해 암호화하지는 않습니다.
1. 준비가 완료되면 약정 정책을 `RequireEncryptAllowDecrypt`로 업데이트하세요. 는 [키 커밋](concepts.md#key-commitment)으로 데이터를 암호화하기 AWS Encryption SDK 시작합니다. 키 커밋 사용 여부와 관계없이 사이퍼텍스트를 복호화할 수 있습니다.
커밋 정책을 `RequireEncryptAllowDecrypt`로 업데이트하기 전에 최신 1.*x* 버전이 생성한 사이퍼텍스트를 복호화하는 애플리케이션의 호스트를 포함하여 모든 호스트에 배포되어 있는지 확인합니다. 버전 1.7.*x* AWS Encryption SDK 이전의 버전은 키 커밋으로 암호화된 메시지를 해독할 수 없습니다.
또한 아직 키 커밋 없이 사이퍼텍스트를 처리하고 있는지 여부를 측정하는 지표를 애플리케이션에 추가하기에 좋은 타이밍입니다. 이렇게 하면 커밋 정책 설정을 언제 `RequireEncryptRequireDecrypt`로 업데이트해도 안전한지 판단할 수 있습니다. Amazon SQS 대기열의 메시지를 암호화하는 것과 같은 일부 애플리케이션의 경우 이하 버전에서 암호화된 모든 사이퍼텍스트가 다시 암호화되거나 삭제될 때까지 오래 기다려야 할 수 있습니다. 암호화된 S3 객체와 같은 다른 애플리케이션의 경우 모든 객체를 다운로드하고, 재암호화, 재업로드해야 할 수 있습니다.
1. 키 커밋 없이 암호화된 메시지가 없는 것이 확실하면 약정 정책을 `RequireEncryptRequireDecrypt`로 업데이트할 수 있습니다. 이 값을 사용하면 항상 키 커밋을 통해 데이터가 암호화되고 복호화됩니다. 이 설정은 기본값이므로 명시적으로 설정할 필요는 없지만 이 설정을 사용하는 것이 좋습니다. 명시적 설정은 애플리케이션에서 키 커밋 없이 암호화된 사이퍼텍스트를 발견할 경우 필요할 수 있는 [디버깅](troubleshooting-migration.md) 및 잠재적 롤백에 도움이 됩니다.
# 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 .
```
------
# AWS KMS 키링 업데이트
의 AWS KMS 키링[AWS Encryption SDK for C](c-language.md), [AWS Encryption SDK for .NET](dot-net.md) 및 [AWS Encryption SDK for JavaScript](javascript.md)는 암호화 및 복호화 시 래핑 키를 지정할 수 있는 [지원 모범 사례를](best-practices.md) 제공합니다. [AWS KMS 검색 키링](use-kms-keyring.md#kms-keyring-discovery)을 생성하는 경우 명시적으로 생성하세요.
**참고**
AWS Encryption SDK for .NET의 최신 버전은 버전 3.0.*x*입니다. AWS Encryption SDK for .NET의 모든 버전은의 2.0.*x*에 도입된 보안 모범 사례를 지원합니다 AWS Encryption SDK. 코드나 데이터를 변경하지 않고도 최신 버전으로 안전하게 업그레이드할 수 있습니다.
의 최신 1.*x* 버전으로 업데이트할 때 [검색 필터를](use-kms-keyring.md#kms-keyring-discovery) 사용하여 복호화할 때 [AWS KMS 검색 키링](use-kms-keyring.md#kms-keyring-discovery) 또는 [AWS KMS 리전 검색 키링](use-kms-keyring.md#kms-keyring-regional)이 사용하는 래핑 키를 특정 래핑 키로 제한할 AWS Encryption SDK수 있습니다 AWS 계정. 검색 키링을 필터링하는 것이 AWS Encryption SDK [모범 사례](best-practices.md)입니다.
이 섹션의 예제는 AWS KMS 리전별 검색 키링에 검색 필터를 추가하는 방법을 보여줍니다.
**마이그레이션에 대해 자세히 알아보기**
모든 AWS Encryption SDK 사용자에 대해에서 커밋 정책을 설정하는 방법에 대해 알아봅니다[커밋 정책 설정](migrate-commitment-policy.md).
AWS Encryption SDK for Java AWS Encryption SDK for Python및 AWS 암호화 CLI 사용자의 경우에서 마스터 키 공급자에 필요한 업데이트에 대해 알아봅니다[AWS KMS 마스터 키 공급자 업데이트](migrate-mkps-v2.md).
애플리케이션에 다음과 같은 코드가 있을 수 있습니다. 이 예제에서는 미국 서부(오레곤)(us-west-2) 리전의 래핑 키만 사용할 수 있는 AWS KMS 리전 검색 키링을 생성합니다. 이 예제는 1.7.*x* 이전 AWS Encryption SDK 버전의 코드를 나타냅니다. 하지만 1.7.*x* 이상 버전에서도 여전히 유효합니다.
------
#### [ C ]
```
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser({ clientProvider, discovery })
```
------
#### [ JavaScript Node.js ]
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({ clientProvider, discovery })
```
------
버전 1.7.*x*부터 모든 검색 키링에 AWS KMS 검색 필터를 추가할 수 있습니다. 이 검색 필터는가 복호화에 사용할 AWS Encryption SDK 수 AWS KMS keys 있는를 지정된 파티션 및 계정의 로 제한합니다. 이 코드를 사용하기 전에 필요한 경우 파티션을 변경하고 예제 계정 ID를 유효한 것으로 바꾸세요.
------
#### [ C ]
전체 예제는 [kms\$1discovery.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/kms_discovery.cpp)를 참조하세요.
```
std::shared_ptr discovery_filter(
KmsKeyring::DiscoveryFilter::Builder("aws")
.AddAccount("111122223333")
.AddAccount("444455556666")
.Build());
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
전체 예제는 [kms\$1filtered\$1discovery.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_filtered_discovery.ts)를 참조하세요.
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
# 커밋 정책 설정
[키 커밋](concepts.md#key-commitment)을 사용하면 암호화된 데이터가 항상 동일한 일반 텍스트로 복호화됩니다. 버전 1.7.*x*부터이 보안 속성을 제공하기 위해는 키 커밋과 함께 새 [알고리즘 제품군](supported-algorithms.md)을 AWS Encryption SDK 사용합니다. 데이터를 암호화하고 복호화할 때 키 커밋 사용 여부를 결정하려면 [커밋 정책](concepts.md#commitment-policy) 구성 설정을 사용합니다. 키 커밋으로 데이터를 암호화하고 복호화하는 것이 [AWS Encryption SDK 모범 사례](best-practices.md)입니다.
커밋 정책 설정은 최신 1.*x* 버전에서 버전 AWS Encryption SDK 2.0.x** 이상으로 마이그레이션하는 마이그레이션 프로세스의 두 번째 단계에서 중요한 부분입니다. 커밋 정책을 설정하고 변경한 후에는 애플리케이션을 프로덕션 환경에 배포하기 전에 철저하게 테스트해야 합니다. 마이그레이션 지침은 [마이그레이션 및 배포 방법 AWS Encryption SDK](migration-guide.md) 섹션을 참조하세요.
2.0.*x* 이상 버전에서 커밋 정책 설정에는 다음과 같은 세 가지 유효한 값이 있습니다. 최신 1.*x* 버전(1.7*x* 버전부터)에서는 `ForbidEncryptAllowDecrypt`만 유효합니다.
+ `ForbidEncryptAllowDecrypt` -는 키 커밋으로 암호화할 AWS Encryption SDK 수 없습니다. 암호화된 사이퍼텍스트를 키 커밋 사용 여부와 관계없이 복호화할 수 있습니다.
최신 1.*x* 버전에서 이는 유일하게 유효한 값입니다. 이를 통해 키 커밋으로 복호화할 준비가 완전히 완료되기 전까지는 키 커밋으로 암호화하지 않도록 합니다. 이 값을 명시적으로 설정하면 2.0.*x* 이상 버전으로 업그레이드할 때 커밋 정책이 자동으로 `require-encrypt-require-decrypt`로 변경되는 것을 방지할 수 있습니다. 대신, 단계적으로 [커밋 정책을 마이그레이션](#migrate-commitment-policy)할 수 있습니다.
+ `RequireEncryptAllowDecrypt` -는 AWS Encryption SDK 항상 키 커밋으로 암호화합니다. 암호화된 사이퍼텍스트를 키 커밋 사용 여부와 관계없이 복호화할 수 있습니다. 이 값은 버전 2.0.*x*에 추가되었습니다.
+ `RequireEncryptRequireDecrypt` -는 AWS Encryption SDK 항상 키 커밋으로 암호화 및 복호화합니다. 이 값은 버전 2.0.*x*에 추가되었습니다. 이는 버전 2.0.*x* 이상에서 기본값입니다.
최신 1.*x* 버전에서 유일하게 유효한 커밋 정책 값은 `ForbidEncryptAllowDecrypt`입니다. 2.0.*x* 이상 버전으로 마이그레이션한 후 준비가 되는 대로 [커밋 정책을 단계적으로 변경](migration-guide.md)할 수 있습니다. 키 커밋 없이 암호화된 메시지가 없는 것이 확인되기 전에는 커밋 정책을 `RequireEncryptRequireDecrypt`로 업데이트하지 마세요.
다음 예제는 최신 1.*x* 버전 및 2.0.*x* 이상 버전에서 커밋 정책을 설정하는 방법을 보여줍니다. 기술은 프로그래밍 언어에 따라 달라집니다.
**마이그레이션에 대해 자세히 알아보기**
AWS Encryption SDK for Java AWS Encryption SDK for Python및 AWS 암호화 CLI의 경우에서 마스터 키 공급자에 필요한 변경 사항에 대해 알아봅니다[AWS KMS 마스터 키 공급자 업데이트](migrate-mkps-v2.md).
AWS Encryption SDK for C 및의 경우의 키링에 대한 선택적 업데이트에 대해 AWS Encryption SDK for JavaScript알아봅니다[AWS KMS 키링 업데이트](migrate-keyrings-v2.md).
## 커밋 정책 설정 방법
커밋 정책을 설정하는 데 사용하는 방법은 각 언어 구현마다 조금씩 다릅니다. 이 예제에서는 해당 작업 방법을 보여줍니다. 커밋 정책을 변경하기 전에 [마이그레이션 및 배포 방법](migration-guide.md)에서 다단계 접근 방식을 검토하세요.
------
#### [ C ]
버전 1.7.*x*부터 `aws_cryptosdk_session_set_commitment_policy` 함수를 AWS Encryption SDK for C사용하여 암호화 및 복호화 세션에 커밋 정책을 설정합니다. 설정한 커밋 정책은 해당 세션에서 호출된 모든 암호화 및 복호화 작업에 적용됩니다.
`aws_cryptosdk_session_new_from_keyring` 및 `aws_cryptosdk_session_new_from_cmm` 함수는 버전 1.7.*x*에서 더 이상 사용되지 않으며 버전 2.0.*x*에서 제거되었습니다. 이러한 함수는 세션을 반환하는 `aws_cryptosdk_session_new_from_keyring_2` 및 `aws_cryptosdk_session_new_from_cmm_2` 함수로 대체됩니다.
최신 1.*x* 버전에서 `aws_cryptosdk_session_new_from_keyring_2` 및 `aws_cryptosdk_session_new_from_cmm_2`를 사용한 경우 `COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT` 커밋 정책 값을 사용하여 `aws_cryptosdk_session_set_commitment_policy` 함수를 호출해야 합니다. 2.0.*x* 이상 버전의 경우 이 함수를 호출하는 것은 선택 사항이며 유효한 값을 모두 사용합니다. 2.0.*x* 이상 버전의 기본 커밋 정책은 `COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT`입니다.
전체 예를 보려면 [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)를 참조하세요.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Create an AWS KMS keyring */
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
/* Create an encrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_session *encrypt_session = aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(encrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
...
/* Encrypt your data */
size_t plaintext_consumed_output;
aws_cryptosdk_session_process(encrypt_session,
ciphertext_output,
ciphertext_buf_sz_output,
ciphertext_len_output,
plaintext_input,
plaintext_len_input,
&plaintext_consumed_output)
...
/* Create a decrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
struct aws_cryptosdk_session *decrypt_session = *aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(decrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
/* Decrypt your ciphertext */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(decrypt_session,
plaintext_output,
plaintext_buf_sz_output,
plaintext_len_output,
ciphertext_input,
ciphertext_len_input,
&ciphertext_consumed_output)
```
------
#### [ C\$1 / .NET ]
`require-encrypt-require-decrypt` 값은 AWS Encryption SDK for .NET의 모든 버전에서 기본 커밋 정책입니다. 모범 사례로 명시적으로 설정할 수 있지만 필수 사항은 아닙니다. 그러나 AWS Encryption SDK for .NET을 사용하여 키 커밋 AWS Encryption SDK 없이의 다른 언어 구현으로 암호화된 사이퍼텍스트를 해독하는 경우 커밋 정책 값을 `REQUIRE_ENCRYPT_ALLOW_DECRYPT` 또는 로 변경해야 합니다`FORBID_ENCRYPT_ALLOW_DECRYPT`. 그러지 않으면 사이퍼텍스트 복호화 시도가 실패합니다.
AWS Encryption SDK for .NET에서의 인스턴스에 커밋 정책을 설정합니다 AWS Encryption SDK. `CommitmentPolicy` 파라미터를 사용하여 `AwsEncryptionSdkConfig` 객체를 인스턴스화하고 구성 객체를 사용하여 AWS Encryption SDK 인스턴스를 생성합니다. 그런 다음 구성된 AWS Encryption SDK 인스턴스의 `Encrypt()` 및 `Decrypt()` 메서드를 호출합니다.
이 예에서는 커밋 정책을 `require-encrypt-allow-decrypt`로 설정합니다.
```
// Instantiate the material providers
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
CommitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var encryptionContext = new Dictionary()
{
{"purpose", "test"}encryptionSdk
};
var createKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);
// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
// Decrypt your ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = keyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
------
#### [ AWS Encryption CLI ]
AWS 암호화 CLI에서 커밋 정책을 설정하려면 `--commitment-policy` 파라미터를 사용합니다. 이 파라미터는 버전 1.8.*x*에 도입되었습니다.
최신 1.*x* 버전의 경우 `--encrypt` 또는 `--decrypt` 명령에서 `--wrapping-keys` 파라미터를 사용할 때는 `forbid-encrypt-allow-decrypt` 값이 있는 `--commitment-policy` 파라미터가 필요합니다. 그러지 않으면 `--commitment-policy` 파라미터가 유효하지 않게 됩니다.
2.1.*x* 및 이상 버전에서는 `--commitment-policy` 파라미터가 선택 사항이며 키 커밋 없이 암호화된 사이퍼텍스트를 암호화하거나 복호화하지 않는 `require-encrypt-require-decrypt` 값이 기본값입니다. 하지만 유지 관리 및 문제 해결에 도움이 되도록 모든 암호화 및 복호화 호출에서 커밋 정책을 명시적으로 설정하는 것이 좋습니다.
이 예에서는 커밋 정책을 설정합니다. 또한 1.8.*x* 버전부터 `--master-keys` 파라미터를 대체하는 `--wrapping-keys` 파라미터를 사용합니다. 자세한 내용은 [AWS KMS 마스터 키 공급자 업데이트](migrate-mkps-v2.md)을 참조하세요. 전체 예제는 [AWS 암호화 CLI의 예](crypto-cli-examples.md) 섹션을 참조하세요.
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data - no change to algorithm suite used
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext - supports key commitment on 1.7 and later
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
#### [ Java ]
버전 1.7.*x*부터 AWS Encryption SDK 클라이언트를 나타내는 객체`AwsCrypto`인의 인스턴스에 커밋 정책을 AWS Encryption SDK for Java설정합니다. 이 커밋 정책 설정은 해당 클라이언트에서 호출된 모든 암호화 및 복호화 작업에 적용됩니다.
`AwsCrypto()` 생성자는의 최신 1.*x* 버전에서는 더 이상 사용되지 AWS Encryption SDK for Java 않으며 버전 2.0.*x*에서는 제거됩니다. 새 `Builder` 클래스, `Builder.withCommitmentPolicy()` 메서드, `CommitmentPolicy` 열거 유형으로 대체됩니다.
최신 1.*x* 버전의 `Builder` 클래스에는 `Builder.withCommitmentPolicy()` 메서드와 `CommitmentPolicy.ForbidEncryptAllowDecrypt` 인수가 필요합니다. 2.0.*x* 버전부터 `Builder.withCommitmentPolicy()` 메서드는 선택 사항이고 기본값은 `CommitmentPolicy.RequireEncryptRequireDecrypt`입니다.
전체 예제는 [SetCommitmentPolicyExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/SetCommitmentPolicyExample.java)를 참조하세요.
```
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
.build();
// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Encrypt your plaintext data
CryptoResult encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
// Decrypt your ciphertext
CryptoResult decryptResult = crypto.decryptData(
masterKeyProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
```
------
#### [ JavaScript ]
버전 1.7.*x*부터 AWS Encryption SDK 클라이언트를 인스턴스화하는 새 `buildClient` 함수를 호출할 때 커밋 정책을 설정할 AWS Encryption SDK for JavaScript수 있습니다. `buildClient` 함수는 커밋 정책을 나타내는 열거형 값을 사용합니다. 암호화 및 복호화 시 커밋 정책을 적용하는 업데이트된 `encrypt` 및 `decrypt` 함수를 반환합니다.
최신 1.*x* 버전에서는 `buildClient` 함수에 `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT` 인수가 필요합니다. 2.0.*x* 버전부터 커밋 정책 인수는 선택 사항이고 기본값은 `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`입니다.
브라우저에 자격 증명을 설정하려면 명령문이 필요하다는 점을 제외하면 Node.js 코드와 브라우저의 코드는 동일합니다.
다음 예제에서는 AWS KMS 키링을 사용하여 데이터를 암호화합니다. 새 `buildClient` 함수는 커밋 정책을 `FORBID_ENCRYPT_ALLOW_DECRYPT`로 설정하며 이는 최신 1.*x* 버전의 기본값입니다. `buildClient`에서 반환되는 업그레이드된 `encrypt` 및 `decrypt` 함수는 사용자가 설정한 커밋 정책을 적용합니다.
```
import { buildClient } from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create an AWS KMS keyring
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
// Encrypt your plaintext data
const { ciphertext } = await encrypt(keyring, plaintext, { encryptionContext: context })
// Decrypt your ciphertext
const { decrypted, messageHeader } = await decrypt(keyring, ciphertext)
```
------
#### [ Python ]
버전 1.7.*x*부터 AWS Encryption SDK 클라이언트를 나타내는 새 객체`EncryptionSDKClient`인의 인스턴스에 커밋 정책을 AWS Encryption SDK for Python설정합니다. 설정한 커밋 정책은 해당 클라이언트 인스턴스를 사용하는 모든 `encrypt` 및 `decrypt` 호출에 적용됩니다.
최신 1.*x* 버전의 `EncryptionSDKClient` 생성자에는 `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT` 열거형 값이 필요합니다. 2.0.*x* 버전부터 커밋 정책 인수는 선택 사항이고 기본값은 `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`입니다.
이 예제에서는 새 `EncryptionSDKClient` 생성자를 사용하고 커밋 정책을 1.7.*x* 기본값으로 설정합니다. 생성자는 AWS Encryption SDK를 나타내는 클라이언트를 인스턴스화합니다. 이 클라이언트에서 `encrypt`, `decrypt` 또는 `stream` 메서드를 호출하면 설정한 커밋 정책이 적용됩니다. 또한이 예제에서는 암호화 및 복호화 AWS KMS keys 시기를 지정하는 `StrictAwsKmsMasterKeyProvider` 클래스의 새 생성자를 사용합니다.
전체 예제는 [set\$1commitment.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/set_commitment.py)를 참조하세요.
```
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[aws_kms_key]
)
# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
source=source_plaintext,
encryption_context=encryption_context,
master_key_provider=aws_kms_strict_master_key_provider
)
# Decrypt your ciphertext
decrypted, decrypt_header = client.decrypt(
source=ciphertext,
master_key_provider=aws_kms_strict_master_key_provider
)
```
------
#### [ Rust ]
`require-encrypt-require-decrypt` 값은 AWS Encryption SDK for Rust의 모든 버전에서 기본 커밋 정책입니다. 모범 사례로 명시적으로 설정할 수 있지만 필수 사항은 아닙니다. 그러나 AWS Encryption SDK for Rust를 사용하여 키 커밋 AWS Encryption SDK 없이의 다른 언어 구현으로 암호화된 사이퍼텍스트를 해독하는 경우 커밋 정책 값을 `REQUIRE_ENCRYPT_ALLOW_DECRYPT` 또는 로 변경해야 합니다`FORBID_ENCRYPT_ALLOW_DECRYPT`. 그러지 않으면 사이퍼텍스트 복호화 시도가 실패합니다.
AWS Encryption SDK for Rust에서의 인스턴스에 커밋 정책을 설정합니다 AWS Encryption SDK. `comitment_policy` 파라미터를 사용하여 `AwsEncryptionSdkConfig` 객체를 인스턴스화하고 구성 객체를 사용하여 AWS Encryption SDK 인스턴스를 생성합니다. 그런 다음 구성된 AWS Encryption SDK 인스턴스의 `Encrypt()` 및 `Decrypt()` 메서드를 호출합니다.
이 예에서는 커밋 정책을 `forbid-encrypt-allow-decrypt`로 설정합니다.
```
// Configure the commitment policy on the AWS Encryption SDK instance
let esdk_config = AwsEncryptionSdkConfig::builder()
.commitment_policy(ForbidEncryptAllowDecrypt)
.build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
// Create your encryption context
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create an AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
// Encrypt your plaintext data
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
// Decrypt your ciphertext
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
```
------
#### [ Go ]
```
import (
"context"
mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
)
// Instantiate the AWS Encryption SDK client
commitPolicyForbidEncryptAllowDecrypt := mpltypes.ESDKCommitmentPolicyForbidEncryptAllowDecrypt
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{CommitmentPolicy: &commitPolicyForbidEncryptAllowDecrypt})
if err != nil {
panic(err)
}
// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
o.Region = KmsKeyRegion
})
// Optional: Create an encryption context
encryptionContext := map[string]string{
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create an AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyId,
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
panic(err)
}
// Encrypt your plaintext data
res, err := forbidEncryptClient.Encrypt(context.Background(), esdktypes.EncryptInput{
Plaintext: []byte(exampleText),
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
// Decrypt your ciphertext
decryptOutput, err := forbidEncryptClient.Decrypt(context.Background(), esdktypes.DecryptInput{
Ciphertext: res.Ciphertext,
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
```
------
# 최신 버전으로의 마이그레이션 문제 해결
애플리케이션을 버전 2.0.*x* 이상으로 업데이트하기 전에의 최신 1.*x* 버전으로 AWS Encryption SDK업데이트 AWS Encryption SDK 하고 완전히 배포합니다. 이렇게 하면 2.0.*x* 이상 버전으로 업데이트할 때 발생할 수 있는 대부분의 오류를 방지하는 데 도움이 됩니다. 예를 포함한 자세한 지침은 [마이그레이션 AWS Encryption SDK](migration.md) 섹션을 참조하세요.
**중요**
최신 1.*x* 버전이 AWS Encryption SDK의 1.7.*x* 또는 이상 버전인지 확인하세요.
**참고**
**AWS 암호화 CLI**:이 가이드에서 버전 1.7.*x*에 대한 참조는 AWS 암호화 CLI 버전 1.8.*x*에 AWS Encryption SDK 적용됩니다. 이 가이드에서 버전 2.0.*x*에 대한 참조는 AWS Encryption CLI의 2.1.*x*에 AWS Encryption SDK 적용됩니다.
새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요.
이 항목은 발생할 수 있는 가장 일반적인 오류를 인식하고 해결하는 데 도움이 되도록 설계되었습니다.
**Topics**
+ [더 이상 사용되지 않거나 제거된 객체](#deprecated-removed)
+ [구성 충돌: 커밋 정책 및 알고리즘 제품군](#configuration-conflict_1)
+ [구성 충돌: 커밋 정책 및 사이퍼텍스트](#configuration-conflict_2)
+ [키 커밋 검증 실패](#commitment-failed)
+ [기타 암호화 오류](#encrypt-failed)
+ [기타 복호화 오류](#decrypt-failed)
+ [롤백 고려 사항](#migration-rollback)
## 더 이상 사용되지 않거나 제거된 객체
버전 2.0.*x*에는 버전 1.7.*x*에서 더 이상 사용되지 않는 레거시 생성자, 메서드, 함수 및 클래스 제거를 비롯한 몇 가지 주요 변경 사항이 포함되어 있습니다. 컴파일러 오류, 가져오기 오류, 구문 오류 및 기호를 찾을 수 없음 오류(프로그래밍 언어에 따라 다름)를 방지하려면 먼저 프로그래밍 언어에 AWS Encryption SDK 맞는 최신 1.*x* 버전의 로 업그레이드합니다. (1.7.*x* 이상 버전이어야 합니다.) 최신 1.*x* 버전을 사용하는 경우 원본 기호가 제거되기 전에 대체 요소 사용을 시작할 수 있습니다.
2.0.*x* 이상 버전으로 즉시 업그레이드해야 하는 경우 사용 중인 프로그래밍 언어의 [변경 로그를 참조하고](about-versions.md) 기존 기호를 변경 로그에서 권장하는 기호로 바꾸세요.
## 구성 충돌: 커밋 정책 및 알고리즘 제품군
[커밋 정책](concepts.md#commitment-policy)과 충돌하는 알고리즘 제품군을 지정하는 경우 *구성 충돌* 오류가 발생하여 암호화 호출이 실패합니다.
이러한 유형의 오류를 방지하려면 알고리즘 제품군을 지정하지 마세요. 기본적으로 AWS Encryption SDK 는 커밋 정책과 호환되는 가장 안전한 알고리즘을 선택합니다. 그러나 서명하지 않은 알고리즘 제품군과 같이 알고리즘 제품군을 지정해야 하는 경우 커밋 정책과 호환되는 알고리즘 제품군을 선택해야 합니다.
| 커밋 정책 | 호환 가능한 알고리즘 제품군 |
| --- | --- |
| ForbidEncryptAllowDecrypt | 다음과 같이 키 커밋이 *없는* 모든 알고리즘 세트:AES\$1256\$1GCM\$1IV12\$1TAG16\$1HKDF\$1SHA384\$1ECDSA\$1P384([03 78](algorithms-reference.md))(서명 있음) `AES_256_GCM_IV12_TAG16_HKDF_SHA256`([01 78](algorithms-reference.md))(서명 없음) |
| RequireEncryptAllowDecryptRequireEncryptRequireDecrypt | 다음과 같이 키 커밋이 *있는* 모든 알고리즘 세트:AES\$1256\$1GCM\$1HKDF\$1SHA512\$1COMMIT\$1KEY\$1ECDSA\$1P384([05 78](algorithms-reference.md))(서명 있음) `AES_256_GCM_HKDF_SHA512_COMMIT_KEY`([04 78](algorithms-reference.md))(서명 없음) |
알고리즘 세트를 지정하지 않은 상태에서 이 오류가 발생하는 경우, [암호화 자료 관리자](concepts.md#crypt-materials-manager)(CMM)가 충돌하는 알고리즘 세트를 선택했을 수 있습니다. 기본 CMM은 충돌하는 알고리즘 세트를 선택하지 않지만 사용자 지정 CMM은 충돌하는 알고리즘 세트를 선택할 수 있습니다. 도움이 필요하면 사용자 지정 CMM 문서 섹션을 참조하세요.
## 구성 충돌: 커밋 정책 및 사이퍼텍스트
`RequireEncryptRequireDecrypt` [커밋 정책](concepts.md#commitment-policy)에서는 AWS Encryption SDK 가 [키 커밋](concepts.md#key-commitment) 없이 암호화된 메시지를 복호화하는 것을 허용하지 않습니다. 키 커밋 없이 메시지를 복호화 AWS Encryption SDK 하도록에 요청하면 *구성 충돌* 오류가 반환됩니다.
이 오류를 방지하려면 `RequireEncryptRequireDecrypt` 커밋 정책을 설정하기 전에 키 커밋 없이 암호화된 모든 사이퍼텍스트를 키 커밋으로 복호화하고 다시 암호화하거나 다른 애플리케이션에서 처리해야 합니다. 이 오류가 발생하는 경우 충돌하는 사이퍼텍스트에 대해 오류를 반환하거나 커밋 정책을 일시적으로 `RequireEncryptAllowDecrypt`로 변경할 수 있습니다.
1.7.*x* 이하 버전에서 최신 1.*x*(1.7.*x* 이상 버전) 버전으로 먼저 업그레이드하지 않고 2.0.*x* 버전으로 업그레이드했기 때문에 이 오류가 발생한 경우 최신 1.*x* 버전으로 [롤백하고](#migration-rollback) 2.0.*x* 이상 버전으로 업그레이드하기 전에 해당 버전을 모든 호스트에 배포하는 것을 고려하세요. 도움말은 [마이그레이션 및 배포 방법 AWS Encryption SDK](migration-guide.md)를 참조하십시오.
## 키 커밋 검증 실패
키 커밋으로 암호화된 메시지를 복호화할 때 *키 커밋 검증 실패* 오류 메시지가 표시될 수 있습니다. 이는 [암호화된 메시지](concepts.md#DEK)의 데이터 키가 메시지의 고유 데이터 키와 동일하지 않아 복호화 호출이 실패했음을 나타냅니다. 복호화 중에 데이터 키를 검증함으로써 [키 커밋](concepts.md#key-commitment)은 메시지를 복호화하여 두 개 이상의 일반 텍스트가 생성될 수 있는 메시지를 복호화하지 못하도록 보호합니다.
이 오류는 복호화하려는 암호화된 메시지가 AWS Encryption SDK에서 반환되지 않았음을 나타냅니다. 수동으로 만든 메시지이거나 데이터 손상의 결과일 수 있습니다. 이 오류가 발생하면 애플리케이션에서 메시지를 거부하고 계속하거나 새 메시지 처리를 중지할 수 있습니다.
## 기타 암호화 오류
암호화는 여러 가지 이유로 실패할 수 있습니다. [AWS KMS 검색 키링](use-kms-keyring.md#kms-keyring-discovery)이나 [검색 모드의 마스터 키 제공자](migrate-mkps-v2.md)를 사용하여 메시지를 암호화할 수 없습니다.
암호화에 [사용할 권한](use-kms-keyring.md#kms-keyring-permissions)이 있는 래핑 키가 있는 키링 또는 마스터 키 제공자를 지정해야 합니다. 권한에 대한 도움말은 *AWS Key Management Service 개발자 안내서*의 [키 정책 보기](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html) 및에 대한 액세스 결정을 AWS KMS keys참조하세요. [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html)
## 기타 복호화 오류
암호화된 메시지의 복호화 시도가 실패했다는 것은 AWS Encryption SDK 가 메시지의 암호화된 데이터 키를 복호화할 수 없거나 복호화하지 않는다는 뜻입니다.
래핑 키를 지정하는 키링 또는 마스터 키 공급자를 사용한 경우는 지정한 래핑 키만 AWS Encryption SDK 사용합니다. 의도한 래핑 키를 사용하고 있는지, 래핑 키 중 하나 이상에 대한 `kms:Decrypt` 권한이 있는지 확인하세요. 를 폴백 AWS KMS keys으로 사용하는 경우 검색 [AWS KMS 키링 또는 검색](use-kms-keyring.md#kms-keyring-discovery) [모드의 마스터 키 공급자를 사용하여 메시지를 복호화해 볼 수 있습니다](migrate-mkps-v2.md). 작업이 성공하면 일반 텍스트를 반환하기 전에 메시지 복호화에 사용된 키가 신뢰할 수 있는 키인지 확인하세요.
## 롤백 고려 사항
애플리케이션이 데이터를 암호화하거나 복호화하는 데 실패하는 경우 일반적으로 코드 기호, 키링, 마스터 키 제공자 또는 [커밋 정책](concepts.md#commitment-policy)을 업데이트하여 문제를 해결할 수 있습니다. 하지만 애플리케이션을 AWS Encryption SDK의 이하 버전으로 롤백하는 것이 최선이라고 판단하는 경우도 있습니다.
롤백해야 하는 경우에는 조심해서 수행하세요. 1.7.*x* AWS Encryption SDK 이전의 버전은 [키 커](concepts.md#key-commitment)밋으로 암호화된 사이퍼텍스트를 해독할 수 없습니다.
+ 최신 1.*x* 버전에서 AWS Encryption SDK 의 이하 버전으로 롤백하는 것이 보통 안전합니다. 이하 버전에서 지원되지 않는 기호와 객체를 사용하려면 코드를 변경한 내용을 취소해야 할 수 있습니다.
+ 2.0.*x* 이상 버전에서 키 커밋(커밋 정책을 `RequireEncryptAllowDecrypt`로 설정)을 사용해 암호화를 시작했다면 1.7.*x* 버전으로 롤백할 수 있지만 그보다 이하 버전으로는 롤백할 수 없습니다. 1.7.*x* AWS Encryption SDK 이전의 버전은 [키 커](concepts.md#key-commitment)밋으로 암호화된 사이퍼텍스트를 해독할 수 없습니다.
모든 호스트가 키 커밋으로 복호화하기 전에 실수로 키 커밋을 사용한 암호화를 활성화한 경우 롤백하는 대신 롤아웃을 계속하는 것이 최선일 수 있습니다. 메시지가 일시적이거나 안전하게 삭제할 수 있는 경우에는 메시지 손실과 함께 롤백을 고려해 볼 수 있습니다. 롤백이 필요한 경우 모든 메시지를 복호화하고 다시 암호화하는 도구를 작성하는 것을 고려할 수 있습니다.