기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 최신 버전으로의 마이그레이션 문제 해결
애플리케이션을 버전 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)밋으로 암호화된 사이퍼텍스트를 해독할 수 없습니다.
모든 호스트가 키 커밋으로 복호화하기 전에 실수로 키 커밋을 사용한 암호화를 활성화한 경우 롤백하는 대신 롤아웃을 계속하는 것이 최선일 수 있습니다. 메시지가 일시적이거나 안전하게 삭제할 수 있는 경우에는 메시지 손실과 함께 롤백을 고려해 볼 수 있습니다. 롤백이 필요한 경우 모든 메시지를 복호화하고 다시 암호화하는 도구를 작성하는 것을 고려할 수 있습니다.