기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 외부 키 스토어 문제 해결
외부 키 스토어와 관련된 대부분의 문제에 대한 해결 방법은 각 예외와 함께 AWS KMS 표시되는 오류 메시지 또는 [외부 키 스토어](xks-connect-disconnect.md)를 외부 키 스토어 프록시에 연결하려는 시도가 실패할 때 AWS KMS 가 반환하는 연결 [오류 코드](#fix-xks-connection)로 표시됩니다. 그러나 몇몇 문제는 조금 더 복잡합니다.
외부 키 스토어 문제를 진단할 때는 먼저 원인을 찾습니다. 이렇게 하면 해결 방법의 범위가 좁아지고 문제 해결이 보다 효율적으로 이루어집니다.
+ AWS KMS - [외부 키 스토어 구성](create-xks-keystore.md#xks-requirements)의 잘못된 값과 AWS KMS같은 문제가 내에 있을 수 있습니다.
+ 외부 - 외부 키 스토어 프록시 AWS KMS, 외부 키 관리자, 외부 키 또는 VPC 엔드포인트 서비스의 구성 또는 작업 문제를 포함하여 외부에서 문제가 발생할 수 있습니다.
+ 네트워킹 - 연결 또는 네트워킹 문제일 수 있습니다(예: 프록시 엔드포인트, 포트, IP 스택 또는 프라이빗 DNS 이름 또는 도메인 문제).
**참고**
외부 키 스토어의 관리 작업이 실패하면 여러 가지 예외가 생성됩니다. 그러나 암호화 작업은 외부 키 스토어의 외부 구성 또는 연결 상태와 관련된 모든 실패에 `KMSInvalidStateException` 대해 AWS KMS 를 반환합니다. 문제를 식별하려면 함께 제공되는 오류 메시지 텍스트를 사용합니다.
[ConnectCustomKeyStore](xks-connect-disconnect.md) 작업은 연결 프로세스가 완료되기 전에 빠르게 성공합니다. 연결 프로세스의 성공 여부를 확인하려면 외부 키 스토어의 [연결 상태](xks-connect-disconnect.md#xks-connection-state)를 확인합니다. 연결 프로세스가 실패하면 AWS KMS 는 원인을 설명하고 해결 방법을 제안하는 [연결 오류 코드](#xks-connection-error-codes)를 반환합니다.
**Topics**
+ [외부 키 스토어에 대한 문제 해결 도구](#xks-troubleshooting-tools)
+ [구성 오류](#fix-xks-configuration)
+ [외부 키 스토어 연결 오류](#fix-xks-connection)
+ [지연 시간 및 제한 시간 오류](#fix-xks-latency)
+ [인증 자격 증명 오류](#fix-xks-credentials)
+ [키 상태 오류](#fix-unavailable-xks-keys)
+ [복호화 오류](#fix-xks-decrypt)
+ [외부 키 오류](#fix-external-key)
+ [프록시 문제](#fix-xks-proxy)
+ [프록시 권한 부여 문제](#fix-xks-authorization)
## 외부 키 스토어에 대한 문제 해결 도구
AWS KMS 는 외부 키 스토어 및 해당 키의 문제를 식별하고 해결하는 데 도움이 되는 여러 도구를 제공합니다. 이러한 도구를 외부 키 스토어 프록시 및 외부 키 관리자와 함께 제공되는 도구와 결합하여 사용하세요.
**참고**
외부 키 스토어 프록시와 외부 키 관리자는 외부 키 스토어와 해당 KMS 키를 생성하고 유지 관리하는 더 쉬운 방법을 제공할 수 있습니다. 자세한 내용은 외부 도구 설명서를 참조하세요.
**AWS KMS 예외 및 오류 메시지**
AWS KMS 는 발생하는 모든 문제에 대한 자세한 오류 메시지를 제공합니다. AWS KMS 예외에 대한 추가 정보는 [https://docs.aws.amazon.com/kms/latest/APIReference/](https://docs.aws.amazon.com/kms/latest/APIReference/) 및 AWS SDKs. AWS KMS 콘솔을 사용하더라도 이러한 참조가 유용할 수 있습니다. 예를 들어, `CreateCustomKeyStores` 작업에 대한 [Errors](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateCustomKeyStore.html#API_CreateCustomKeyStore_Errors)(오류) 목록을 참조하세요.
외부 키 저장소 프록시의 성능을 최적화하기 위해 AWS KMS 는 지정된 집계 기간인 5분 내에 프록시의 신뢰성을 기반으로 예외를 반환합니다. 500 내부 서버 오류, 503 서비스 사용 불가 또는 연결 제한 시간이 발생하는 경우 신뢰성이 높은 프록시에서 `KMSInternalException`을 반환하고 자동 재시도를 트리거하여 요청이 최종적으로 성공할 수 있도록 합니다. 하지만 신뢰성이 낮은 프록시는 `KMSInvalidStateException`을 반환합니다. 자세한 내용은 [외부 키 저장소 모니터링](https://docs.aws.amazon.com/kms/latest/developerguide/xks-monitoring.html)을 참조하세요.
외부 키 스토어의 KMS 키를 사용하여 다른 AWS 서비스의 리소스를 보호하는 경우와 같이 다른 AWS 서비스에 문제가 표시되는 경우, AWS 이 서비스는 문제를 식별하는 데 도움이 되는 추가 정보를 제공할 수 있습니다. AWS 서비스가 메시지를 제공하지 않는 경우 KMS 키 사용을 기록하는 [CloudTrail 로그](logging-using-cloudtrail.md)에서 오류 메시지를 볼 수 있습니다.
**[CloudTrail 로그](logging-using-cloudtrail.md)**
AWS KMS 콘솔의 작업을 포함한 모든 AWS KMS API 작업은 AWS CloudTrail 로그에 기록됩니다.는 성공 및 실패한 작업에 대한 로그 항목을 AWS KMS 기록합니다. 실패한 작업의 경우 로그 항목에 AWS KMS 예외 이름(`errorCode`)과 오류 메시지(`errorMessage`)가 포함됩니다. 이 정보를 사용하여 오류를 식별하고 해결할 수 있습니다. 예제는 [외부 키 스토어에서 KMS 키로 복호화 실패](ct-decrypt.md#ct-decrypt-xks-fail) 섹션을 참조하세요.
로그 항목에는 요청 ID도 포함됩니다. 요청이 외부 키 스토어 프록시에 도달한 경우 로그 항목의 요청 ID를 사용하여 프록시 로그에서 해당 요청을 찾을 수 있습니다(프록시에서 제공하는 경우).
**[CloudWatch 지표](monitoring-cloudwatch.md#kms-metrics)**
AWS KMS 는 지연 시간, 제한, 프록시 오류, 외부 키 관리자 상태, TLS 인증서가 만료될 때까지의 일수, 프록시 인증 자격 증명의 보고된 수명을 포함하여 외부 키 스토어의 운영 및 성능에 대한 자세한 Amazon CloudWatch 지표를 기록합니다. 이러한 지표를 사용하여 임박한 문제가 발생하기 전에 알리는 외부 키 스토어 및 CloudWatch 경보 작동을 위한 데이터 모델을 개발할 수 있습니다.
AWS KMS 에서는 외부 키 스토어 지표를 모니터링하기 위해 CloudWatch 경보를 생성할 것을 권장합니다. 이러한 경보는 문제가 발생하기 전에 문제의 조기 징후를 알려줍니다.
**[모니터링 그래프](xks-monitoring.md)**
AWS KMS 는 AWS KMS 콘솔의 각 외부 키 스토어에 대한 세부 정보 페이지에 외부 키 스토어 CloudWatch 지표의 그래프를 표시합니다. 그래프의 데이터를 사용하여 오류의 원인을 찾고, 임박한 문제를 감지하고, 기준선을 설정하고, CloudWatch 경보 임계값을 세부 조정할 수 있습니다. 모니터링 그래프 해석 및 해당 데이터 사용에 대한 자세한 내용은 [외부 키 저장소 모니터링](xks-monitoring.md) 섹션을 참조하세요.
**외부 키 스토어 및 KMS 키 표시**
AWS KMS 는 외부 키 스토어 및 KMS 키에 대한 자세한 정보를 AWS KMS 콘솔의 외부 키 스토어와 [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) 및 [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) 작업에 대한 응답으로 표시합니다. 외부 키 스토어의 [연결 상태](xks-connect-disconnect.md#xks-connection-state) 및 KMS 키와 연결된 외부 키의 ID를 비롯하여 문제 해결에 사용할 수 있는 정보와 함께 외부 키 스토어 및 KMS 키에 대한 특수 필드 등이 표시됩니다. 자세한 내용은 [외부 키 저장소 보기](view-xks-keystore.md)을 참조하세요.
**[XKS 프록시 테스트 클라이언트](https://github.com/aws-samples/aws-kms-xksproxy-test-client)**
AWS KMS 는 외부 키 스토어 프록시가 [AWS KMS 외부 키 스토어 프록시 API 사양을](https://github.com/aws/aws-kms-xksproxy-api-spec/) 준수하는지 확인하는 오픈 소스 테스트 클라이언트를 제공합니다. 이 테스트 클라이언트를 사용하여 외부 키 스토어 프록시의 문제를 식별하고 해결할 수 있습니다.
## 구성 오류
외부 키 스토어를 생성할 때 [프록시 인증 자격 증명](create-xks-keystore.md#require-credential), [프록시 URI 엔드포인트](create-xks-keystore.md#require-endpoint), [프록시 URI 경로](create-xks-keystore.md#require-path) 및 [VPC 엔드포인트 서비스 이름](create-xks-keystore.md#require-vpc-service-name)과 같은 외부 키 스토어의 *구성*을 포함하는 속성 값을 지정합니다. 가 속성 값의 오류를 AWS KMS 감지하면 작업이 실패하고 결함이 있는 값을 나타내는 오류를 반환합니다.
잘못된 값을 수정하여 많은 구성 문제를 해결할 수 있습니다. 외부 키 스토어를 연결 해제하지 않고도 잘못된 프록시 URI 경로 또는 프록시 인증 자격 증명을 수정할 수 있습니다. 고유성 요구 사항을 포함하여 이러한 값의 정의는 [사전 조건 수집](create-xks-keystore.md#xks-requirements) 섹션을 참조하세요. 이러한 값 업데이트에 대한 지침은 [외부 키 저장소 속성 편집](update-xks-keystore.md) 섹션을 참조하세요.
프록시 URI 경로 및 프록시 인증 자격 증명 값의 오류를 방지하려면 외부 키 스토어를 생성하거나 업데이트할 때 [프록시 구성 파일](create-xks-keystore.md#proxy-configuration-file)을 AWS KMS 콘솔에 업로드합니다. 외부 키 스토어 프록시 또는 외부 키 관리자가 제공하는 프록시 URI 경로 및 프록시 인증 자격 증명 값이 있는 JSON 기반 파일입니다. AWS KMS API 작업에는 프록시 구성 파일을 사용할 수 없지만 파일의 값을 사용하여 프록시의 값과 일치하는 API 요청에 대한 파라미터 값을 제공할 수 있습니다.
### 일반 구성 오류
**예외**: `CustomKeyStoreInvalidStateException`(`CreateKey`), `KMSInvalidStateException`(암호화 작업), `XksProxyInvalidConfigurationException`(관리 작업, `CreateKey` 제외)
[**연결 오류 코드**](#xks-connection-error-codes): `XKS_PROXY_INVALID_CONFIGURATION`, `XKS_PROXY_INVALID_TLS_CONFIGURATION`
[퍼블릭 엔드포인트 연결이](choose-xks-connectivity.md#xks-connectivity-public-endpoint) 있는 외부 키 스토어의 경우는 외부 키 스토어를 생성하고 업데이트할 때 속성 값을 AWS KMS 테스트합니다. [VPC 엔드포인트 서비스 연결](choose-xks-connectivity.md#xks-vpc-connectivity)이 있는 외부 키 스토어의 경우 AWS KMS 는 외부 키 스토어를 연결하고 업데이트할 때 속성 값을 테스트합니다.
**참고**
비동기식인 `ConnectCustomKeyStore` 작업은 외부 키 스토어를 외부 키 스토어 프록시에 연결하려는 시도가 실패하더라도 성공할 수 있습니다. 이 경우 예외는 없지만 외부 키 스토어의 연결 상태는 Failed(실패)이며 연결 오류 코드는 오류 메시지를 설명합니다. 자세한 내용은 [외부 키 스토어 연결 오류](#fix-xks-connection) 단원을 참조하십시오.
가 속성 값의 오류를 AWS KMS 감지하면 작업이 실패하고 다음 오류 메시지 중 하나와 `XksProxyInvalidConfigurationException` 함께가 반환됩니다.
| |
| --- |
| 외부 키 스토어 프록시가 잘못된 URI 경로 때문에 요청을 거부했습니다. 외부 키 스토어의 URI 경로를 확인하고 필요한 경우 업데이트합니다. |
+ [프록시 URI 경로](create-xks-keystore.md#require-path)는 프록시 API에 대한 AWS KMS 요청의 기본 경로입니다. APIs 이 경로가 올바르지 않으면 프록시에 대한 모든 요청이 실패합니다. 외부 키 스토어의 [현재 프록시 URI 경로를 보려면](view-xks-keystore.md) AWS KMS 콘솔 또는 `DescribeCustomKeyStores` 작업을 사용합니다. 올바른 프록시 URI 경로를 찾으려면 외부 키 스토어 프록시 설명서를 참조하세요. 프록시 URI 경로 값을 수정하는 방법에 대한 도움말은 [외부 키 저장소 속성 편집](update-xks-keystore.md) 섹션을 참조하세요.
+ 외부 키 스토어 프록시의 프록시 URI 경로는 외부 키 스토어 프록시 또는 외부 키 관리자 업데이트에 따라 변경될 수 있습니다. 이러한 변경 사항에 대한 자세한 내용은 외부 키 스토어 프록시 또는 외부 키 관리자의 설명서를 참조하세요.
| |
| --- |
| `XKS_PROXY_INVALID_TLS_CONFIGURATION`AWS KMS 가 외부 키 스토어 프록시에 대한 TLS 연결을 설정할 수 없습니다. 인증서를 포함하여 TLS 구성을 확인합니다. |
+ 모든 외부 키 스토어 프록시에는 TLS 인증서가 필요합니다. 외부 키 스토어에 대해 지원되는 공인 인증 기관(CA)에서 TLS 인증서를 발급받아야 합니다. 지원되는 CA 목록은 AWS KMS 외부 키 스토어 프록시 API 사양의 [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities)(신뢰할 수 있는 인증 기관)를 참조하세요.
+ 퍼블릭 엔드포인트 연결의 경우 TLS 인증서의 주체 일반 이름(CN)은 외부 키 스토어 프록시에 대한 [프록시 URI 엔드포인트](create-xks-keystore.md#require-endpoint)의 도메인 이름과 일치해야 합니다. 예를 들어 퍼블릭 엔드포인트가 https://myproxy.xks.example.com인 경우 TLS, TLS 인증서의 CN은 `myproxy.xks.example.com` 또는 `*.xks.example.com`이어야 합니다.
+ VPC 엔드포인트 서비스 연결의 경우 TLS 인증서의 주체 일반 이름(CN)이 [VPC 엔드포인트 서비스](create-xks-keystore.md#require-vpc-service-name)의 프라이빗 DNS 이름과 일치해야 합니다. 예를 들어 프라이빗 DNS 이름이 myproxy-private.xks.example.com인 경우 TLS 인증서의 CN은 `myproxy-private.xks.example.com` 또는 `*.xks.example.com`이어야 합니다.
+ TLS 인증서는 만료될 수 없습니다. TLS 인증서의 만료 날짜를 확인하려면 [OpenSSL](https://www.openssl.org/)과 같은 SSL 도구를 사용합니다. 외부 키 스토어와 연결된 TLS 인증서의 만료 날짜를 모니터링하려면 [XksProxyCertificateDaysToExpire](monitoring-cloudwatch.md#metric-xks-proxy-certificate-days-to-expire) CloudWatch 지표를 사용합니다. TLS 인증 만료 날짜까지의 일수는 AWS KMS 콘솔의 [**모니터링** 섹션에](xks-monitoring.md)도 표시됩니다.
+ [퍼블릭 엔드포인트 연결](choose-xks-connectivity.md#xks-connectivity-public-endpoint)을 사용하는 경우 SSL 테스트 도구를 사용하여 SSL 구성을 테스트합니다. 잘못된 인증서 연결로 인해 TLS 연결 오류가 발생할 수 있습니다.
### VPC 엔드포인트 서비스 연결 구성 오류
**예외**: `XksProxyVpcEndpointServiceNotFoundException`, `XksProxyVpcEndpointServiceInvalidConfigurationException`
일반적인 연결 문제 외에도 VPC 엔드포인트 서비스 연결을 사용하여 외부 키 스토어를 생성, 연결 또는 업데이트하는 동안 다음과 같은 문제가 발생할 수 있습니다.는 외부 키 스토어를 [생성](create-xks-keystore.md), [연결](xks-connect-disconnect.md) 및 [업데이트](update-xks-keystore.md)하는 동안 VPC 엔드포인트 서비스 연결을 사용하여 외부 키 스토어의 속성 값을 AWS KMS 테스트합니다. 구성 오류로 인해 관리 작업이 실패하면 다음 예외가 생성됩니다.
| |
| --- |
| XksProxyVpcEndpointServiceNotFoundException |
원인은 다음 중 하나일 수 있습니다.
+ VPC 엔드포인트 서비스 이름이 잘못되었습니다. 외부 키 스토어의 VPC 엔드포인트 서비스 이름이 올바르고 외부 키 스토어의 프록시 URI 엔드포인트 값과 일치하는지 확인합니다. VPC 엔드포인트 서비스 이름을 찾으려면 [Amazon VPC 콘솔](https://console.aws.amazon.com/vpc) 또는 [DescribeVpcEndpointServices](https://docs.aws.amazon.com/AmazonVPC/latest/APIReference/DescribeVpcEndpointServices.html) 작업을 사용합니다. 기존 외부 키 스토어의 VPC 엔드포인트 서비스 이름과 프록시 URI 엔드포인트를 찾으려면 AWS KMS 콘솔 또는 [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) 작업을 사용합니다. 자세한 내용은 [외부 키 저장소 보기](view-xks-keystore.md)을 참조하세요.
+ VPC 엔드포인트 서비스는 외부 키 스토어 AWS 리전 와 다른에 있을 수 있습니다. VPC 엔드포인트 서비스와 외부 키 스토어가 동일한 리전에 있는지 확인합니다. (`us-east-1`과 같은 리전 이름의 외부 이름은 com.amazonaws.vpce.useast-1.vpce-svc-example과 같은 VPC 엔드포인트 서비스 이름의 일부입니다.) 외부 키 스토어의 VPC 엔드포인트 서비스에 대한 요구 사항 목록은 [VPC 엔드포인트 서비스](create-xks-keystore.md#require-vpc-service-name) 섹션을 참조하세요. VPC 엔드포인트 서비스 또는 외부 키 스토어를 다른 리전으로 이동할 수 없습니다. 그러나 VPC 엔드포인트 서비스와 동일한 리전에서 새 외부 키 스토어를 생성할 수 있습니다. 자세한 내용은 [VPC 엔드포인트 서비스 연결 구성](vpc-connectivity.md) 및 [외부 키 저장소 생성](create-xks-keystore.md) 섹션을 참조하세요.
+ AWS KMS 는 VPC 엔드포인트 서비스에 허용되는 보안 주체가 아닙니다. VPC 엔드포인트 서비스에 대한 **Allow principals**(보안 주체 허용) 목록에는 `cks.kms.{{}}.amazonaws.com` 값(예: `cks.kms.{{eu-west-3}}.amazonaws.com`)이 포함되어야 합니다. 이 값을 추가하는 방법에 대한 지침은AWS PrivateLink 가이드**의 [Manage permissions](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)(권한 관리)를 참조하세요.
| |
| --- |
| XksProxyVpcEndpointServiceInvalidConfigurationException |
이 오류는 VPC 엔드포인트 서비스가 다음 요구 사항 중 하나를 충족하지 못할 때 발생합니다.
+ VPC에는 각각 다른 가용 영역에 있는 두 개 이상의 프라이빗 서브넷이 필요합니다. VPC에 서브넷을 추가하는 방법에 대한 도움말은 Amazon VPC 사용 설명서**의 [VPC에 서브넷 생성](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-subnets.html#create-subnets)을 참조하세요.
+ [VPC 엔드포인트 서비스 유형](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html)은 Gateway Load Balancer가 아닌 Network Load Balancer를 사용해야 합니다.
+ VPC 엔드포인트 서비스에 대해 수락이 필요하지 않아야 합니다(**Acceptance required**(수락 필요)는 false여야 함). 각 연결 요청을 수동으로 수락해야 하는 경우 VPC 엔드포인트 서비스를 사용하여 외부 키 스토어 프록시에 연결할 수 AWS KMS 없습니다. 자세한 내용은AWS PrivateLink 가이드**의 [Accept or reject connection requests](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#accept-reject-connection-requests)(연결 요청 수락 또는 거부)를 참조하세요.
+ VPC 엔드포인트 서비스에는 퍼블릭 도메인의 하위 도메인인 프라이빗 DNS 이름이 있어야 합니다. 예를 들어 프라이빗 DNS 이름이 `https://myproxy-private.xks.example.com`인 경우 `xks.example.com` 또는 `example.com` 도메인에 퍼블릭 DNS 서버가 있어야 합니다. VPC 엔드포인트 서비스의 프라이빗 DNS 이름을 보거나 변경하려면AWS PrivateLink 가이드**의 [Manage DNS names for VPC endpoint services](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html)(VPC 엔드포인트 서비스의 DNS 이름 관리)를 참조하세요.
+ 프라이빗 DNS 이름 도메인의 **Domain verification status**(도메인 확인 상태)는 `verified`여야 합니다. 프라이빗 DNS 이름 도메인의 확인 상태를 보고 업데이트하려면 [5단계: 프라이빗 DNS 이름 도메인 확인](vpc-connectivity.md#xks-private-dns) 섹션을 참조하세요. 필수 텍스트 레코드를 추가한 후 업데이트된 확인 상태가 표시되는 데 몇 분 정도 걸릴 수 있습니다.
**참고**
프라이빗 DNS 도메인은 퍼블릭 도메인의 하위 도메인인 경우에만 확인할 수 있습니다. 그렇지 않으면 필요한 TXT 레코드를 추가한 후에도 프라이빗 DNS 도메인의 확인 상태가 변경되지 않습니다.
+ AWS KMS 와 외부 키 스토어 프록시 사이의 방화벽이 IPv4를 통해 포트 443에서 proxy. AWS KMS communicates의 포트 443과 주고받는 트래픽을 허용하는지 확인합니다. 이 값은 구성할 수 없습니다.
+ VPC 엔드포인트 서비스의 프라이빗 DNS 이름은 외부 키 스토어의 [프록시 URI 엔드포인트](create-xks-keystore.md#require-endpoint) 값과 일치해야 합니다. VPC 엔드포인트 서비스 연결이 있는 외부 키 스토어의 경우 프록시 URI 엔드포인트는 `https://` 뒤에 VPC 엔드포인트 서비스의 프라이빗 DNS 이름이 와야 합니다. 프록시 URI 엔드포인트 값을 보려면 [외부 키 저장소 보기](view-xks-keystore.md) 섹션을 참조하세요. 프록시 URI 엔드포인트 값을 변경하려면 [외부 키 저장소 속성 편집](update-xks-keystore.md) 섹션을 참조하세요.
## 외부 키 스토어 연결 오류
외부 키 스토어 프록시에 [외부 키 스토어를 연결하는 프로세스](about-xks-connecting.md)는 완료하는 데 5분가량 걸립니다. 빨리 실패하지 않는 한, `ConnectCustomKeyStore` 작업은 속성 없이 HTTP 200 응답 및 JSON 객체를 반환합니다. 하지만 이러한 초기 응답은 연결이 성공했음을 의미하지는 않습니다. 외부 키 스토어가 연결되어 있는지 파악하려면 해당 [연결 상태](xks-connect-disconnect.md#xks-connection-state)를 확인합니다. 연결이 실패하면 외부 키 스토어의 연결 상태가 로 변경`FAILED`되고 실패 원인을 설명하는 [연결 오류 코드가](#xks-connection-error-codes) AWS KMS 반환됩니다.
**참고**
사용자 지정 키 스토어의 연결 상태가 `FAILED`면 재연결을 시도하기에 앞서 사용자 지정 키 스토어를 연결 해제해야 합니다. 연결 상태가 `FAILED`이면 사용자 지정 키 스토어를 연결할 수 없습니다.
외부 키 스토어의 연결 상태를 보려면 다음을 수행하세요.
+ [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) 응답에서 `ConnectionState` 요소의 값을 확인합니다.
+ AWS KMS 콘솔에서 **연결 상태가** 외부 키 스토어 테이블에 나타납니다. 또한 각 외부 키 스토어의 세부 정보 페이지에서 **General configuration**(일반 구성) 섹션에 **Connection state**(연결 상태)가 표시됩니다.
연결 상태가 `FAILED`인 경우 연결 오류 코드는 오류를 설명하는 데 도움이 됩니다.
연결 오류 코드를 보려면 다음을 수행하세요.
+ [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) 응답에서 `ConnectionErrorCode` 요소의 값을 확인합니다. 이 요소는 `ConnectionState`가 `FAILED`인 경우에만 `DescribeCustomKeyStores` 응답에 나타납니다.
+ AWS KMS 콘솔에서 연결 오류 코드를 보려면 외부 키 스토어의 세부 정보 페이지에서 **실패** 값 위에 마우스를 올려 놓습니다.
### 외부 키 스토어의 연결 오류 코드
다음 연결 오류 코드는 외부 키 스토어에 적용됩니다.
`INTERNAL_ERROR`
AWS KMS 내부 오류로 인해에서 요청을 완료하지 못했습니다. 요청을 다시 시도하세요. `ConnectCustomKeyStore` 요청의 경우, 사용자 지정 키 스토어를 연결 해제한 후 다시 연결을 시도하세요.
`INVALID_CREDENTIALS`
`XksProxyAuthenticationCredential` 값 중 하나 또는 둘 다 지정된 외부 키 스토어 프록시에서 유효하지 않습니다.
`NETWORK_ERRORS`
네트워크 오류로 인해가 사용자 지정 키 스토어를 백업 키 스토어에 연결할 수 AWS KMS 없습니다.
`XKS_PROXY_ACCESS_DENIED`
AWS KMS 요청은 외부 키 스토어 프록시에 대한 액세스가 거부됩니다. 외부 키 스토어 프록시에 권한 부여 규칙이 있는 경우 AWS KMS 가 사용자를 대신하여 프록시와 통신하도록 허용하는지 확인합니다.
`XKS_PROXY_INVALID_CONFIGURATION`
구성 오류로 인해 외부 키 스토어가 해당 프록시에 연결할 수 없습니다. `XksProxyUriPath`의 값을 확인합니다.
`XKS_PROXY_INVALID_RESPONSE`
AWS KMS 는 외부 키 스토어 프록시의 응답을 해석할 수 없습니다. 이 연결 오류 코드가 반복적으로 표시되면 외부 키 스토어 프록시 공급업체에 알립니다.
`XKS_PROXY_INVALID_TLS_CONFIGURATION`
AWS KMS TLS 구성이 유효하지 않아가 외부 키 스토어 프록시에 연결할 수 없습니다. 외부 키 스토어 프록시가 TLS 1.2 또는 1.3을 지원하는지 확인합니다. 또한 TLS 인증서가 만료되지 않았는지, `XksProxyUriEndpoint` 값의 호스트 이름과 일치하는지, [Trusted Certificate Authorities](https://github.com/aws/aws-kms-xksproxy-api-spec/blob/main/TrustedCertificateAuthorities)(신뢰할 수 있는 인증 기관) 목록에 포함된 신뢰할 수 있는 인증 기관에서 서명했는지 확인합니다.
`XKS_PROXY_NOT_REACHABLE`
AWS KMS 가 외부 키 스토어 프록시와 통신할 수 없습니다. `XksProxyUriEndpoint`와 `XksProxyUriPath`가 올바른지 확인합니다. 외부 키 스토어 프록시용 도구를 사용하여 프록시가 활성 상태이고 해당 네트워크에서 사용 가능한지 확인합니다. 또한 외부 키 관리자 인스턴스가 제대로 작동하고 있는지 확인합니다. 프록시가 모든 외부 키 관리자 인스턴스를 사용할 수 없다고 보고하는 경우 이 연결 오류 코드와 함께 연결 시도가 실패합니다.
`XKS_PROXY_TIMED_OUT`
AWS KMS 는 외부 키 스토어 프록시에 연결할 수 있지만 프록시는 할당된 시간 AWS KMS 내에에 응답하지 않습니다. 이 연결 오류 코드가 반복적으로 표시되면 외부 키 스토어 프록시 공급업체에 알립니다.
`XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION`
Amazon VPC 엔드포인트 서비스 구성은 AWS KMS 외부 키 스토어의 요구 사항을 준수하지 않습니다.
+ VPC 엔드포인트 서비스는 호출자의 AWS 계정에 있는 인터페이스 엔드포인트에 대한 엔드포인트 서비스여야 합니다.
+ 각각 다른 가용 영역에 있는 두 개 이상의 서브넷에 연결된 NLB(Network Load Balancer)가 있어야 합니다.
+ `Allow principals` 목록에는와 `cks.kms..amazonaws.com`같은 리전의 AWS KMS 서비스 보안 주체가 포함되어야 합니다`cks.kms.us-east-1.amazonaws.com`.
+ 연결 요청 [수락](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html)을 요구하지 *않아야* 합니다.
+ 프라이빗 DNS 이름이 있어야 합니다. `VPC_ENDPOINT_SERVICE` 연결이 있는 외부 키 스토어의 프라이빗 DNS 이름은 해당 AWS 리전에서 고유해야 합니다.
+ 프라이빗 DNS 이름 도메인의 [확인 상태](https://docs.aws.amazon.com/vpc/latest/privatelink/verify-domains.html)는 `verified`여야 합니다.
+ [TLS 인증서](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/create-tls-listener.html)는 엔드포인트에 도달할 수 있는 프라이빗 DNS 호스트 이름을 지정합니다.
`XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND`
AWS KMS 가 외부 키 스토어 프록시와 통신하는 데 사용하는 VPC 엔드포인트 서비스를 찾을 수 없습니다. `XksProxyVpcEndpointServiceName`이 올바르고 AWS KMS 서비스 보안 주체에 Amazon VPC 엔드포인트 서비스에 대한 서비스 소비자 권한이 있는지 확인합니다.
## 지연 시간 및 제한 시간 오류
**예외**: `CustomKeyStoreInvalidStateException`(`CreateKey`), `KMSInvalidStateException`(암호화 작업), `XksProxyUriUnreachableException`(관리 작업)
[**연결 오류 코드**](#xks-connection-error-codes): `XKS_PROXY_NOT_REACHABLE`, `XKS_PROXY_TIMED_OUT`
가 250밀리초 제한 시간 간격 내에 프록시에 연결할 AWS KMS 수 없는 경우 예외를 반환하고 `CreateCustomKeyStore`를 `UpdateCustomKeyStore` 반환합니다`XksProxyUriUnreachableException`. 암호화 작업은 문제를 설명하는 오류 메시지와 함께 표준 `KMSInvalidStateException`을 반환합니다. `ConnectCustomKeyStore` 실패하면 문제를 설명하는 [연결 오류 코드를](#fix-xks-connection) AWS KMS 반환합니다.
제한 시간 오류는 요청을 다시 시도하여 해결할 수 있는 일시적인 문제일 수 있습니다. 문제가 지속되면 외부 키 스토어 프록시가 활성 상태이고 네트워크에 연결되어 있으며 해당 프록시 URI 엔드포인트, 프록시 URI 경로 및 VPC 엔드포인트 서비스 이름(있는 경우)이 외부 키 스토어에서 올바른지 확인합니다. 또한 외부 키 관리자가 외부 키 스토어의 AWS 리전 에 가까운지 확인합니다. 이러한 값을 업데이트해야 하는 경우 [외부 키 저장소 속성 편집](update-xks-keystore.md) 섹션을 참조하세요.
지연 시간 패턴을 추적하려면 AWS KMS 콘솔의 [**Monitoring**(모니터링) 섹션](xks-monitoring.md)에서 [`XksProxyLatency`](monitoring-cloudwatch.md#metric-xks-proxy-latency) CloudWatch 지표와 **Average latency**(평균 지연 시간) 그래프(해당 지표 기반)를 사용합니다. 외부 키 스토어 프록시는 지연 시간과 제한 시간을 추적하는 로그와 지표를 생성할 수도 있습니다.
| |
| --- |
| `XksProxyUriUnreachableException`AWS KMS 는 외부 키 스토어 프록시와 통신할 수 없습니다. 일시적인 네트워크 문제일 수 있습니다. 이 오류가 반복적으로 표시되는 경우 외부 키 스토어 프록시가 활성 상태이고 네트워크에 연결되어 있는지, 해당 엔드포인트 URI가 외부 키 스토어에서 올바른지 확인합니다. |
+ 외부 키 스토어 프록시가 250밀리초 제한 시간 간격 내에 AWS KMS 프록시 API 요청에 응답하지 않았습니다. 이는 일시적인 네트워크 문제나 프록시의 작동 또는 성능 문제를 나타낼 수 있습니다. 다시 시도해도 문제가 해결되지 않으면 외부 키 스토어 프록시 관리자에게 알리세요.
지연 시간 및 제한 시간 오류는 종종 연결 실패로 나타납니다. [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) 작업이 실패하면 외부 키 스토어의 *연결 상태가* 로 변경`FAILED`되고 오류를 설명하는 *연결 오류 코드가* AWS KMS 반환됩니다. 연결 오류 코드 목록과 오류 해결을 위한 제안 사항은 [외부 키 스토어의 연결 오류 코드](#xks-connection-error-codes) 섹션을 참조하세요. **모든 사용자 지정 키 스토어**와 **외부 키 스토어**의 연결 코드 목록은 외부 키 스토어에 적용됩니다. 다음 연결 오류는 지연 시간 및 제한 시간과 관련이 있습니다.
| |
| --- |
| `XKS_PROXY_NOT_REACHABLE`
-또는-
`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`AWS KMS 는 외부 키 스토어 프록시와 통신할 수 없습니다. 외부 키 스토어 프록시가 활성 상태이고 네트워크에 연결되어 있는지, 해당 URI 경로와 엔드포인트 URI 또는 VPC 서비스 이름이 외부 키 스토어에서 올바른지 확인합니다. |
이 오류는 다음과 같은 이유로 발생할 수 있습니다.
+ 외부 키 스토어 프록시가 활성 상태가 아니거나 네트워크에 연결되어 있지 않습니다.
+ 외부 키 스토어 구성의 [프록시 URI 엔드포인트](create-xks-keystore.md#require-endpoint), [프록시 URI 경로](create-xks-keystore.md#require-path) 또는 [VPC 엔드포인트 서비스 이름](create-xks-keystore.md#require-vpc-service-name)(해당하는 경우) 값에 오류가 있습니다. 외부 키 스토어 구성을 보려면 [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) 작업을 사용하거나 AWS KMS 콘솔에서 외부 키 스토어의 [세부 정보 페이지를 확인합니다](view-xks-keystore.md).
+ AWS KMS 와 외부 키 스토어 프록시 간의 네트워크 경로에 포트 오류와 같은 네트워크 구성 오류가 있을 수 있습니다. IPv4를 통해 포트 443의 외부 키 스토어 프록시와 AWS KMS 통신합니다. 이 값은 구성할 수 없습니다.
+ 외부 키 스토어 프록시가 [GetHealthStatus](keystore-external.md#concept-proxy-apis) 응답에서 모든 외부 키 관리자 인스턴스가 `UNAVAILABLE`이라고 보고하면 `XKS_PROXY_NOT_REACHABLE`의 `ConnectionErrorCode`와 함께 [ConnectCustomKeyStore](https://docs.aws.amazon.com/kms/latest/APIReference/API_ConnectCustomKeyStore.html) 작업이 실패합니다. 도움말은 외부 키 관리자 설명서를 참조하세요.
+ 이 오류는 외부 키 관리자와 외부 키 스토어가 AWS 리전 있는 간의 물리적 거리가 길기 때문에 발생할 수 있습니다. AWS 리전 와 외부 키 관리자 간의 ping 지연 시간(네트워크 왕복 시간(RTT))은 35밀리초 이하여야 합니다. 외부 키 관리자에 AWS 리전 더 가까운에서 외부 키 스토어를 생성하거나 외부 키 관리자를에 더 가까운 데이터 센터로 이동해야 할 수 있습니다 AWS 리전.
| |
| --- |
| `XKS_PROXY_TIMED_OUT`
-또는-
`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException`외부 키 스토어 프록시가 제시간에 응답하지 않았기 때문에AWS KMS 가 요청을 거부했습니다. 요청을 다시 시도하세요. 이 오류가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 보고하세요. |
이 오류는 다음과 같은 이유로 발생할 수 있습니다.
+ 이 오류는 외부 키 관리자와 외부 키 스토어 프록시 간의 물리적 거리가 멀기 때문에 발생할 수 있습니다. 가능한 경우 외부 키 스토어 프록시를 외부 키 관리자에 더 가깝게 이동합니다.
+ 프록시가 요청의 볼륨과 빈도를 처리하도록 설계되지 않은 경우 제한 시간 오류가 발생할 수 있습니다 AWS KMS. CloudWatch 지표가 지속적인 문제를 나타내는 경우 외부 키 스토어 프록시 관리자에게 알리세요.
+ 외부 키 관리자와 외부 키 스토어에 대한 Amazon VPC 간의 연결이 제대로 작동하지 않는 경우 제한 시간 오류가 발생할 수 있습니다. 를 사용하는 경우 VPC와 외부 키 관리자가 효과적으로 통신할 수 있는지 AWS Direct Connect확인합니다. 문제를 해결하는 데 도움이 필요하면 Direct Connect 사용 설명서의 [문제 해결을 참조하세요 AWS Direct Connect](https://docs.aws.amazon.com/directconnect/latest/UserGuide/Troubleshooting.html).
| |
| --- |
| `XKS_PROXY_TIMED_OUT`
-또는-
`CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`, `XksProxyUriUnreachableException` 외부 키 스토어 프록시가 할당된 시간 내에 요청에 응답하지 않았습니다. 요청을 다시 시도하세요. 이 오류가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 보고하세요. |
+ 이 오류는 외부 키 관리자와 외부 키 스토어 프록시 간의 물리적 거리가 멀기 때문에 발생할 수 있습니다. 가능한 경우 외부 키 스토어 프록시를 외부 키 관리자에 더 가깝게 이동합니다.
## 인증 자격 증명 오류
**예외**: `CustomKeyStoreInvalidStateException`(`CreateKey`), `KMSInvalidStateException`(암호화 작업), `XksProxyIncorrectAuthenticationCredentialException`(`CreateKey` 이외의 관리 작업)
외부 키 스토어 프록시 AWS KMS 에서에 대한 인증 자격 증명을 설정하고 유지 관리합니다. 그런 다음 외부 키 스토어 AWS KMS 를 생성할 때 자격 증명 값을 알려줍니다. 인증 자격 증명을 변경하려면 외부 키 스토어 프록시에서 변경합니다. 그런 다음 외부 키 스토어에 대한 [자격 증명을 업데이트](update-xks-keystore.md#xks-edit-name)합니다. 프록시가 자격 증명을 교체하는 경우 외부 키 스토어에 대한 [자격 증명을 업데이트](update-xks-keystore.md#xks-edit-name)해야 합니다.
외부 키 스토어 프록시가 외부 키 스토어에 대한 [프록시 인증 자격 증명](keystore-external.md#concept-xks-credential)으로 서명된 요청을 인증하지 않는 경우 효과는 요청에 따라 다릅니다.
+ `CreateCustomKeyStore`와 `UpdateCustomKeyStore`는 `XksProxyIncorrectAuthenticationCredentialException`과 함께 실패합니다.
+ `ConnectCustomKeyStore`는 성공하지만 연결은 실패합니다. 연결 상태는 `FAILED`이고 연결 오류 코드는 `INVALID_CREDENTIALS`입니다. 자세한 내용은 [외부 키 스토어 연결 오류](#fix-xks-connection)을 참조하세요.
+ 암호화 작업은 외부 키 저장소의 모든 외부 구성 오류 및 연결 상태 오류에 대하여 `KMSInvalidStateException`를 반환합니다. 함께 제공되는 오류 메시지에 문제가 설명되어 있습니다.
| |
| --- |
| 외부 키 스토어 프록시가 AWS KMS를 인증할 수 없기 때문에 요청을 거부했습니다. 외부 키 스토어의 자격 증명을 확인하고 필요한 경우 업데이트합니다. |
이 오류는 다음과 같은 이유로 발생할 수 있습니다.
+ 외부 키 스토어의 액세스 키 ID 또는 보안 액세스 키가 외부 키 스토어 프록시에 설정된 값과 일치하지 않습니다.
이 오류를 해결하려면 외부 키 스토어의 [프록시 인증 자격 증명을 업데이트](update-xks-keystore.md#xks-edit-name)합니다. 외부 키 스토어를 연결 해제하지 않고 이 변경을 수행할 수 있습니다.
+ AWS KMS 와 외부 키 스토어 프록시 간의 역방향 프록시는 SigV4 서명을 무효화하는 방식으로 HTTP 헤더를 조작할 수 있습니다. 이 오류를 수정하려면 프록시 관리자에게 알리세요.
## 키 상태 오류
**예외**: `KMSInvalidStateException`
`KMSInvalidStateException`은 사용자 지정 키 스토어의 KMS 키에 대해 두 가지 다른 용도로 사용됩니다.
+ `CancelKeyDeletion`과 같은 관리 작업이 실패하고 이 예외를 반환하면 KMS 키의 [키 상태](key-state.md)가 작업과 호환되지 않는 것입니다.
+ 사용자 지정 키 스토어의 KMS 키에 대한 [암호화 작업](kms-cryptography.md#cryptographic-operations)이 `KMSInvalidStateException`과 함께 실패하면 KMS 키의 키 상태에 문제가 있는 것일 수 있습니다. 그러나 암호화 작업은 외부 키 스토어의 모든 외부 구성 오류 및 연결 상태 오류에 `KMSInvalidStateException` 대해 AWS KMS 를 반환합니다. 문제를 식별하려면 예외와 함께 제공되는 오류 메시지를 사용합니다.
AWS KMS API 작업에 필요한 키 상태를 찾으려면 섹션을 참조하세요[키의 AWS KMS 키 상태](key-state.md). KMS 키의 키 상태를 확인하려면 **(고객 관리형 키** 페이지에서 KMS 키의 **상태** 필드를 확인합니다. 또는 [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) 작업을 사용해 응답의 `KeyState` 요소를 확인합니다. 자세한 내용은 [키 식별 및 보기](viewing-keys.md)을 참조하세요.
**참고**
외부 키 스토어에 있는 KMS 키의 키 상태는 연결된 [외부 키](keystore-external.md#concept-external-key)의 상태에 대해 아무 것도 나타내지 않습니다. 외부 키 상태에 대한 자세한 내용을 보려면 외부 키 관리자와 외부 키 스토어 프록시 도구를 사용하세요.
`CustomKeyStoreInvalidStateException`은 KMS 키의 [키 상태](key-state.md)가 아니라 외부 키 스토어의 [연결 상태](xks-connect-disconnect.md#xks-connection-state)를 나타냅니다.
KMS 키의 키 상태가 `Unavailable` 또는 `PendingDeletion`이므로 사용자 지정 스토어의 KMS 키에 대한 암호화 작업이 실패할 수 있습니다. (비활성화된 키에서는 `DisabledException`이 반환됩니다.)
+ KMS 키는 AWS KMS 콘솔에서 KMS `Disabled` 키를 의도적으로 비활성화하거나 [DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html) 작업을 사용하는 경우에만 키 상태가 됩니다. KMS 키가 비활성화된 동안에는 키를 보고 관리할 수 있지만 암호화 작업에 사용할 수는 없습니다. 이 문제를 해결하려면 키를 활성화합니다. 자세한 내용은 [KMS 키 활성화 및 비활성화](enabling-keys.md)을 참조하세요.
+ KMS 키는 외부 키 스토어가 외부 키 스토어 프록시에서 연결 해제되는 경우 `Unavailable` 키 상태가 됩니다. 사용 불가 상태인 KMS 키를 수정하려면 [외부 키 스토어를 다시 연결합니다](xks-connect-disconnect.md). 외부 키 스토어가 다시 연결되고 나면 외부 키 스토어의 KMS 키 상태가 이전 상태(`Enabled` 또는 `Disabled`)로 자동 복구됩니다.
KMS 키는 삭제 예약이 되어 있고 대기 기간에 있는 경우 `PendingDeletion` 키 상태가 됩니다. 삭제 보류 중인 KMS 키의 키 상태 오류는 키가 암호화에 사용되고 있거나 복호화에 필요하기 때문에 삭제해서는 안 됨을 나타냅니다. KMS 키를 다시 활성화하려면 예약된 삭제를 취소한 다음 [키를 활성화](enabling-keys.md)합니다. 자세한 내용은 [키 삭제 예약](deleting-keys-scheduling-key-deletion.md)을 참조하세요.
## 복호화 오류
**예외**: `KMSInvalidStateException`
외부 키 스토어의 KMS 키를 사용한 [복호](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)화 작업이 실패하면 `KMSInvalidStateException`는 외부 키 스토어의 모든 외부 구성 오류 및 연결 상태 오류에 암호화 작업이 사용하는 표준을 AWS KMS 반환합니다. 오류 메시지가 문제를 나타냅니다.
[이중 암호화](keystore-external.md#concept-double-encryption)를 사용하여 암호화된 사이퍼텍스트를 복호화하기 위해 외부 키 관리자는 먼저 외부 키를 사용하여 사이퍼텍스트의 외부 계층을 복호화합니다. 그런 다음 AWS KMS KMS AWS KMS 키의 키 구성 요소를 사용하여 사이퍼텍스트의 내부 계층을 복호화합니다. 유효하지 않거나 손상된 사이퍼텍스트는 외부 키 관리자 또는 AWS KMS에 의해 거부될 수 있습니다.
복호화가 실패하면 `KMSInvalidStateException`과 함께 다음 오류 메시지가 나타납니다. 요청의 사이퍼텍스트 또는 선택적 암호화 컨텍스트에 문제가 있는 것입니다.
| |
| --- |
| 외부 키 스토어 프록시가 지정된 사이퍼텍스트나 추가 인증 데이터가 손상 또는 누락되었거나 유효하지 않기 때문에 요청을 거부했습니다. |
+ 외부 키 스토어 프록시 또는 외부 키 관리자가 사이퍼텍스트 또는 암호화 컨텍스트가 유효하지 않다고 보고하면 일반적으로 전송된 `Decrypt` 요청의 사이퍼텍스트 또는 암호화 컨텍스트에 문제가 있음을 나타냅니다 AWS KMS. `Decrypt` 작업의 경우는 `Decrypt` 요청에서 수신하는 것과 동일한 사이퍼텍스트 및 암호화 컨텍스트를 프록시에 AWS KMS 전송합니다.
이 오류는 플립드 비트와 같은 전송 중 네트워킹 문제로 인해 발생할 수 있습니다. `Decrypt` 요청을 다시 시도하세요. 문제가 지속되면 사이퍼텍스트가 변경되거나 손상되지 않았는지 확인합니다. 또한에 대한 `Decrypt` 요청의 암호화 컨텍스트가 데이터를 암호화한 요청의 암호화 컨텍스트와 AWS KMS 일치하는지 확인합니다.
| |
| --- |
| 암호 복호화를 위해 외부 키 스토어 프록시가 제출한 사이퍼텍스트 또는 암호화 컨텍스트가 손상되었거나 누락되었거나 유효하지 않습니다. |
+ 가 프록시에서 수신한 사이퍼텍스트를 AWS KMS 거부하면 외부 키 관리자 또는 프록시가 유효하지 않거나 손상된 사이퍼텍스트를 반환했음을 나타냅니다 AWS KMS.
이 오류는 플립드 비트와 같은 전송 중 네트워킹 문제로 인해 발생할 수 있습니다. `Decrypt` 요청을 다시 시도하세요. 문제가 지속되면 외부 키 관리자가 제대로 작동하는지, 외부 키 스토어 프록시가 외부 키 관리자로부터 받은 사이퍼텍스트를 변경하지 않았는지 확인한 후 반환합니다 AWS KMS.
## 외부 키 오류
[외부 키](keystore-external.md#concept-external-key)는 KMS 키의 외부 키 구성 요소 역할을 하는 외부 키 관리자의 암호화 키입니다. AWS KMS 는 외부 키에 직접 액세스할 수 없습니다. 외부 키 스토어 프록시를 통해 외부 키 관리자에게 외부 키를 사용하여 데이터를 암호화하거나 사이퍼텍스트를 복호화하도록 요청해야 합니다.
외부 키 스토어에서 KMS 키를 생성할 때 외부 키 관리자에서 외부 키의 ID를 지정합니다. KMS 키를 생성한 후에는 외부 키 ID를 변경할 수 없습니다. KMS 키 관련 문제를 방지하기 위해 `CreateKey` 작업은 외부 키의 ID와 구성을 확인하도록 외부 키 스토어 프록시에 요청합니다. 외부 키가 KMS 키와 함께 사용하기 위한 [요구 사항을 충족](create-xks-keys.md#xks-key-requirements)하지 않는 경우 문제를 식별하는 예외 및 오류 메시지와 함께 `CreateKey` 작업이 실패합니다.
그러나 KMS 키가 생성된 후 문제가 발생할 수 있습니다. 외부 키 문제로 인해 암호화 작업이 실패하면 작업이 실패하고 문제를 나타내는 오류 메시지와 함께 `KMSInvalidStateException`이 반환됩니다.
### 외부 키에 대한 CreateKey 오류
**예외**: `XksKeyAlreadyInUseException`, `XksKeyNotFoundException`, `XksKeyInvalidConfigurationException`
[CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) 작업은 **External key ID**(외부 키 ID)(콘솔) 또는 `XksKeyId`(API) 파라미터에 제공한 외부 키의 ID와 속성을 확인하려고 시도합니다. 이 방법은 KMS 키와 함께 외부 키를 사용하려고 시도하기 전에 조기에 오류를 감지하도록 설계되었습니다.
**외부 키 사용 중**
외부 키 스토어의 각 KMS 키는 다른 외부 키를 사용해야 합니다. `CreateKey`는 KMS 키의 외부 키 ID(XksKeyId)가 외부 키 스토어에서 고유하지 않음을 인식하면 `XksKeyAlreadyInUseException`과 함께 실패합니다.
동일한 외부 키에 대해 여러 ID를 사용하는 경우 `CreateKey`는 중복을 인식하지 않습니다. 그러나 외부 키가 동일한 KMS 키는 AWS KMS 키 구성 요소와 메타데이터가 다르기 때문에 상호 운용할 수 없습니다.
**외부 키를 찾을 수 없음**
외부 키 스토어 프록시가 KMS 키에 대한 외부 키 ID(XksKeyId)를 사용하여 외부 키를 찾을 수 없다고 보고하면 `CreateKey` 작업이 실패하고 다음 오류 메시지와 함께 `XksKeyNotFoundException`을 반환합니다.
| |
| --- |
| 외부 키 스토어 프록시가 외부 키를 찾을 수 없기 때문에 요청을 거부했습니다. |
이 오류는 다음과 같은 이유로 발생할 수 있습니다.
+ KMS 키의 외부 키(`XksKeyId`) ID(XksKeyId)가 유효하지 않을 수 있습니다. 외부 키 프록시가 외부 키를 식별하는 데 사용하는 ID를 찾으려면 외부 키 스토어 프록시 또는 외부 키 관리자 설명서를 참조하세요.
+ 외부 키가 외부 키 관리자에서 삭제되었을 수 있습니다. 조사하려면 외부 키 관리자 도구를 사용합니다. 외부 키가 영구적으로 삭제된 경우 KMS 키와 함께 다른 외부 키를 사용합니다. 외부 키의 목록 또는 요구 사항은 [외부 키 스토어의 KMS 키 요구 사항](create-xks-keys.md#xks-key-requirements) 섹션을 참조하세요.
**외부 키 요구 사항이 충족되지 않음**
외부 키 스토어 프록시에서 외부 키가 KMS 키와 함께 사용하기 위한 [요구 사항을 충족](create-xks-keys.md#xks-key-requirements)하지 않는다고 보고하면 `CreateKey` 작업이 실패하고 다음 오류 메시지 중 하나와 함께 `XksKeyInvalidConfigurationException`을 반환합니다.
| |
| --- |
| 외부 키의 키 사양은 AES\_256이어야 합니다. 지정된 외부 키의 키 사양은 {{}}.입니다. |
+ 외부 키는 키 사양이 AES\_256인 256비트 대칭 암호화 키여야 합니다. 지정된 외부 키가 다른 유형인 경우 이 요구 사항을 충족하는 외부 키의 ID를 지정합니다.
| |
| --- |
| 외부 키의 상태가 ENABLED여야 합니다. 지정된 외부 키의 상태는 {{}}여야 합니다. |
+ 외부 키 관리자에서 외부 키를 활성화해야 합니다. 지정된 외부 키가 활성화되지 않은 경우 외부 키 관리자 도구를 사용하여 활성화하거나 활성화된 외부 키를 지정합니다.
| |
| --- |
| 외부 키의 키 사용에는 ENCRYPT와 DECRYPT가 포함되어야 합니다. 지정된 외부 키의 키 사용은 <{{key-usage}}>입니다. |
+ 외부 키 관리자에서 암호화와 복호화를 위해 외부 키를 구성해야 합니다. 지정된 외부 키에 이러한 작업이 포함되지 않은 경우 외부 키 관리자 도구를 사용하여 작업을 변경하거나 다른 외부 키를 지정합니다.
### 외부 키에 대한 암호화 작업 오류
**예외**: `KMSInvalidStateException`
외부 키 스토어 프록시가 KMS 키와 연결된 외부 키를 찾을 수 없거나 외부 키가 KMS 키와 함께 사용하기 위한 [요구 사항을 충족](create-xks-keys.md#xks-key-requirements)하지 못하면 암호화 작업이 실패합니다.
암호화 작업 중 감지되는 외부 키 문제는 KMS 키를 생성하기 전에 감지된 외부 키 문제보다 해결하기 더 어렵습니다. KMS 키를 생성한 후에는 외부 키 ID를 변경할 수 없습니다. KMS 키가 아직 데이터를 암호화하지 않은 경우 KMS 키를 삭제하고 다른 외부 키 ID로 새 키를 생성할 수 있습니다. 그러나 KMS 키로 생성된 사이퍼텍스트는 키의 키 메타데이터와 키 구성 요소가 다르기 때문에 외부 키가 동일한 키라도 다른 KMS AWS KMS 키로 복호화할 수 없습니다. 대신 가능한 한 외부 키 관리자 도구를 사용하여 외부 키 관련 문제를 해결하세요.
외부 키 스토어 프록시가 외부 키에 문제가 있다고 보고하면 암호화 작업은 문제를 식별하는 오류 메시지와 함께 `KMSInvalidStateException`을 반환합니다.
**외부 키를 찾을 수 없음**
외부 키 스토어 프록시가 KMS 키에 대한 외부 키 ID(XksKeyId)를 사용하여 외부 키를 찾을 수 없다고 보고하면 암호화 작업이 다음 오류 메시지와 함께 `KMSInvalidStateException`을 반환합니다.
| |
| --- |
| 외부 키 스토어 프록시가 외부 키를 찾을 수 없기 때문에 요청을 거부했습니다. |
이 오류는 다음과 같은 이유로 발생할 수 있습니다.
+ KMS 키의 외부 키 ID(`XksKeyId`)가 더 이상 유효하지 않습니다.
KMS 키와 연결된 외부 키 ID를 찾으려면 [KMS 키의 세부 정보를 봅니다](identify-key-types.md#view-xks-key). 외부 키 프록시가 외부 키를 식별하는 데 사용하는 ID를 찾으려면 외부 키 스토어 프록시 또는 외부 키 관리자 설명서를 참조하세요.
AWS KMS 는 외부 키 스토어에서 KMS 키를 생성할 때 외부 키 ID를 확인합니다. 그러나 특히 외부 키 ID 값이 별칭이거나 변경 가능한 이름인 경우 ID가 무효화될 수 있습니다. 기존 KMS 키와 연결된 외부 키 ID는 변경할 수 없습니다. KMS 키로 암호화된 사이퍼텍스트를 복호화하려면 외부 키를 기존 외부 키 ID와 다시 연결해야 합니다.
아직 KMS 키를 사용하여 데이터를 암호화하지 않은 경우 유효한 외부 키 ID로 새 KMS 키를 생성할 수 있습니다. 그러나 KMS 키로 사이퍼텍스트를 생성한 경우 동일한 외부 키를 사용하더라도 다른 KMS 키를 사용하여 사이퍼텍스트를 복호화할 수 없습니다.
+ 외부 키가 외부 키 관리자에서 삭제되었을 수 있습니다. 조사하려면 외부 키 관리자 도구를 사용합니다. 가능하면 외부 키 관리자의 사본 또는 백업에서 [키 구성 요소를 복구](fix-keystore.md#fix-keystore-recover-backing-key)해 봅니다. 외부 키가 영구적으로 삭제되면 연결된 KMS 키로 암호화된 사이퍼텍스트를 복구할 수 없습니다.
**외부 키 구성 오류**
외부 키 스토어 프록시에서 외부 키가 KMS 키와 함께 사용하기 위한 [요구 사항을 충족](create-xks-keys.md#xks-key-requirements)하지 않는다고 보고하면 암호화 작업이 다음 오류 메시지 중 하나와 함께 `KMSInvalidStateException`을 반환합니다.
| |
| --- |
| 외부 키가 요청된 작업을 지원하지 않기 때문에 외부 키 스토어 프록시가 요청을 거부했습니다. |
+ 외부 키가 암호화와 복호화를 모두 지원해야 합니다. 키 사용에 암호화와 복호화가 포함되지 않은 경우 외부 키 관리자 도구를 사용하여 키 사용을 변경합니다.
| |
| --- |
| 외부 키 관리자에서 외부 키가 활성화되지 않았기 때문에 외부 키 스토어 프록시가 요청을 거부했습니다. |
+ 외부 키를 활성화하고 외부 키 관리자에서 사용할 수 있어야 합니다. 외부 키의 상태가 `Enabled`가 아닌 경우 외부 키 관리자 도구를 사용하여 외부 키를 활성화합니다.
## 프록시 문제
**예외:**
`CustomKeyStoreInvalidStateException` (`CreateKey`), `KMSInvalidStateException`(암호화 작업), `UnsupportedOperationException`, `XksProxyUriUnreachableException`, `XksProxyInvalidResponseException`(`CreateKey` 이외의 관리 작업)
외부 키 스토어 프록시는 AWS KMS 와 외부 키 관리자 간의 모든 통신을 중재합니다. 일반 AWS KMS 요청을 외부 키 관리자가 이해할 수 있는 형식으로 변환합니다. 외부 키 스토어 프록시가 [AWS KMS 외부 키 스토어 프록시 API 사양을](https://github.com/aws/aws-kms-xksproxy-api-spec/) 준수하지 않거나가 제대로 작동하지 않거나와 통신할 수 없는 경우 외부 키 스토어에서 KMS 키를 생성하거나 사용할 수 AWS KMS없습니다.
많은 오류가 외부 키 스토어 아키텍처에서의 중요한 역할 때문에 외부 키 스토어 프록시를 언급하지만 이러한 문제는 외부 키 관리자 또는 외부 키에서 발생할 수 있습니다.
이 섹션의 문제는 외부 키 스토어 프록시의 설계 또는 작업 문제와 관련이 있습니다. 이러한 문제를 해결하려면 프록시 소프트웨어를 변경해야 할 수 있습니다. 프록시 관리자에게 문의하세요. 프록시 문제 진단에 도움이 되도록 AWS KMS 는 외부 키 스토어 프록시가 [AWS KMS 외부 키 스토어 프록시 API 사양](https://github.com/aws/aws-kms-xksproxy-api-spec/)을 준수하는지 확인하는 오픈 소스 테스트 클라이언트인 [XKS 프록시 테스트 클라이언트](https://github.com/aws-samples/aws-kms-xksproxy-test-client)를 제공합니다.
| |
| --- |
| `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException` 또는 `XksProxyUriUnreachableException`외부 키 스토어 프록시가 비정상 상태입니다. 이 메시지가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 알리세요. |
+ 이 오류는 외부 키 스토어 프록시의 운영 문제 또는 소프트웨어 오류를 나타낼 수 있습니다. 각 오류를 생성한 AWS KMS API 작업에 대한 CloudTrail 로그 항목을 찾을 수 있습니다. 이 오류는 작업을 다시 시도하여 해결할 수 있습니다. 그러나 이 오류가 지속되면 외부 키 스토어 프록시 관리자에게 알리세요.
+ 외부 키 스토어 프록시가 [GetHealthStatus](keystore-external.md#concept-proxy-apis) 응답에서 모든 외부 키 관리자 인스턴스가 `UNAVAILABLE`이라고 보고하면 이 예외와 함께 외부 키 스토어를 생성하거나 업데이트하려는 시도가 실패합니다. 이 오류가 지속되면 외부 키 관리자 설명서를 참조하세요.
| |
| --- |
| `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException` 또는 `XksProxyInvalidResponseException`AWS KMS 는 외부 키 스토어 프록시의 응답을 해석할 수 없습니다. 이 오류가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 문의하세요. |
+ AWS KMS 프록시가 구문 분석 또는 해석할 AWS KMS 수 없는 정의되지 않은 응답을 반환하면 작업이이 예외를 생성합니다. 이 오류는 일시적인 외부 문제나 산발적인 네트워크 오류로 인해 가끔 발생할 수 있습니다. 그러나 지속되면 외부 키 스토어 프록시가 [AWS KMS 외부 키 스토어 프록시 API 사양](https://github.com/aws/aws-kms-xksproxy-api-spec/)을 준수하지 않는 것일 수 있습니다. 외부 키 스토어 관리자 또는 공급업체에 알리세요.
| |
| --- |
| `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException` 또는 `UnsupportedOperationException`
외부 키 스토어 프록시가 요청된 작업을 암호화 작업을 지원하지 않기 때문에 요청을 거부했습니다. |
+ 외부 키 스토어 프록시는 [AWS KMS 외부 키 스토어 프록시 API 사양](https://github.com/aws/aws-kms-xksproxy-api-spec/)에 정의된 모든 [프록시 API](keystore-external.md#concept-proxy-apis)를 지원해야 합니다. 이 오류는 프록시가 요청과 관련된 작업을 지원하지 않음을 나타냅니다. 외부 키 스토어 관리자 또는 공급업체에 알리세요.
## 프록시 권한 부여 문제
**예외**: `CustomKeyStoreInvalidStateException`, `KMSInvalidStateException`
일부 외부 키 스토어 프록시는 외부 키 사용에 대한 권한 부여 요구 사항을 구현합니다. 외부 키 스토어 프록시는 특정 사용자가 특정 조건에서 특정 작업을 요청할 수 있도록 하는 권한 부여 체계를 설계하고 구현하는 데 허용되지만 필수는 아닙니다. 예를 들어 프록시를 사용하면 사용자가 특정 외부 키로 암호화할 수 있지만 복호화할 수는 없습니다. 자세한 내용은 [외부 키 스토어 프록시 권한 부여(선택 사항)](authorize-xks-key-store.md#xks-proxy-authorization) 단원을 참조하십시오.
프록시 권한 부여는가 프록시에 대한 요청에 AWS KMS 포함하는 메타데이터를 기반으로 합니다. `awsSourceVpc` 및 `awsSourceVpce` 필드는 요청이 VPC 엔드포인트에서 발생하고 호출자가 KMS 키와 동일한 계정에 있는 경우에만 메타데이터에 포함됩니다.
```
"requestMetadata": {
"awsPrincipalArn": string,
"awsSourceVpc": string, // optional
"awsSourceVpce": string, // optional
"kmsKeyArn": string,
"kmsOperation": string,
"kmsRequestId": string,
"kmsViaService": string // optional
}
```
프록시가 권한 부여 실패로 인해 요청을 거부하면 관련 AWS KMS 작업이 실패합니다.는를 `CreateKey` 반환합니다`CustomKeyStoreInvalidStateException`. AWS KMS 암호화 작업은를 반환합니다`KMSInvalidStateException`. 둘 다 다음 오류 메시지를 사용합니다.
| |
| --- |
| 외부 키 스토어 프록시가 작업에 대한 액세스를 거부했습니다. 사용자와 외부 키 모두에 이 작업에 대한 권한이 있는지 확인하고 요청을 다시 시도하세요. |
+ 오류를 해결하려면 외부 키 관리자 또는 외부 키 스토어 프록시 도구를 사용하여 인증에 실패한 이유를 확인합니다. 그런 다음 무단 요청을 유발한 절차를 업데이트하거나 외부 키 스토어 프록시 도구를 사용하여 권한 부여 정책을 업데이트합니다. AWS KMS에서는 이 오류를 해결할 수 없습니다.