외부 키 스토어 문제 해결 - AWS Key Management Service

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

외부 키 스토어 문제 해결

외부 키 스토어와 관련된 대부분의 문제에 대한 해결 방법은 AWS KMS가 각 예외와 함께 표시하는 오류 메시지나 외부 키 스토어 프록시에 외부 키 스토어를 연결하려는 시도가 실패할 때 AWS KMS가 반환하는 연결 오류 코드로 표시됩니다. 그러나 몇몇 문제는 조금 더 복잡합니다.

외부 키 스토어 문제를 진단할 때는 먼저 원인을 찾습니다. 이렇게 하면 해결 방법의 범위가 좁아지고 문제 해결이 보다 효율적으로 이루어집니다.

  • AWS KMS - AWS KMS 안에 문제가 있을 수 있습니다(예: 외부 키 스토어 구성의 잘못된 값).

  • 외부 - AWS KMS 외부에서 문제가 비롯되었을 수 있습니다(예: 외부 키 스토어 프록시, 외부 키 관리자, 외부 키 또는 VPC 엔드포인트 서비스의 구성 또는 작업 문제)

  • 네트워킹 - 연결 또는 네트워킹 문제일 수 있습니다(예: 프록시 엔드포인트, 포트 또는 프라이빗 DNS 이름 또는 도메인 문제).

참고

외부 키 스토어의 관리 작업이 실패하면 여러 가지 예외가 생성됩니다. 그러나 AWS KMS 암호화 작업은 외부 키 스토어의 외부 구성 또는 연결 상태와 관련된 모든 실패에 대하여 KMSInvalidStateException을 반환합니다. 문제를 식별하려면 함께 제공되는 오류 메시지 텍스트를 사용합니다.

ConnectCustomKeyStore 작업은 연결 프로세스가 완료되기 전에 빠르게 성공합니다. 연결 프로세스의 성공 여부를 확인하려면 외부 키 스토어의 연결 상태를 확인합니다. 연결 프로세스가 실패하면 AWS KMS는 원인을 설명하고 해결 방법을 제안하는 연결 오류 코드를 반환합니다.

외부 키 스토어에 대한 문제 해결 도구

AWS KMS는 외부 키 스토어 및 해당 키와 관련된 문제를 식별하고 해결하는 데 도움이 되는 몇 가지 도구를 제공합니다. 이러한 도구를 외부 키 스토어 프록시 및 외부 키 관리자와 함께 제공되는 도구와 결합하여 사용하세요.

참고

외부 키 스토어 프록시와 외부 키 관리자는 외부 키 스토어와 해당 KMS 키를 생성하고 유지 관리하는 더 쉬운 방법을 제공할 수 있습니다. 자세한 내용은 외부 도구 설명서를 참조하세요.

AWS KMS 예외 및 오류 메시지

AWS KMS는 발생하는 문제에 대한 자세한 오류 메시지를 제공합니다. AWS Key Management Service API 참조와 AWS SDK에서 AWS KMS 예외에 대한 추가 정보를 확인할 수 있습니다. AWS KMS 콘솔을 사용하는 경우에도 이러한 참조가 유용할 수 있습니다. 예를 들어, CreateCustomKeyStores 작업에 대한 Errors(오류) 목록을 참조하세요.

외부 키 저장소 프록시의 성능을 최적화하기 위해 AWS KMS는 지정된 집계 기간인 5분 내에 프록시의 신뢰성을 기반으로 예외를 반환합니다. 500 내부 서버 오류, 503 서비스 사용 불가 또는 연결 제한 시간이 발생하는 경우 신뢰성이 높은 프록시에서 KMSInternalException을 반환하고 자동 재시도를 트리거하여 요청이 최종적으로 성공할 수 있도록 합니다. 하지만 신뢰성이 낮은 프록시는 KMSInvalidStateException을 반환합니다. 자세한 내용은 외부 키 저장소 모니터링을 참조하세요.

외부 키 스토어에서 KMS 키를 사용하여 다른 AWS 서비스의 리소스를 보호하는 경우와 같이 다른 AWS 서비스에서 문제가 발생하면 AWS 서비스에서 문제를 식별하는 데 도움이 되는 추가 정보를 제공할 수 있습니다. AWS 서비스에서 메시지를 제공하지 않는 경우 KMS 키 사용을 기록하는 CloudTrail 로그에서 오류 메시지를 볼 수 있습니다.

CloudTrail 로그

AWS KMS 콘솔의 작업을 포함하여 모든 AWS KMS API 작업은 AWS CloudTrail 로그에 기록됩니다. AWS KMS는 성공한 작업과 실패한 작업에 대한 로그 항목을 기록합니다. 실패한 작업의 경우 로그 항목에 AWS KMS 예외 이름(errorCode)과 오류 메시지(errorMessage)가 포함됩니다. 이 정보를 사용하여 오류를 식별하고 해결할 수 있습니다. 예시는 외부 키 스토어에서 KMS 키로 복호화 실패을 확인하세요.

로그 항목에는 요청 ID도 포함됩니다. 요청이 외부 키 스토어 프록시에 도달한 경우 로그 항목의 요청 ID를 사용하여 프록시 로그에서 해당 요청을 찾을 수 있습니다(프록시에서 제공하는 경우).

CloudWatch 지표

AWS KMS는 지연 시간, 제한, 프록시 오류, 외부 키 관리자 상태, TLS 인증서 만료까지 남은 일수, 프록시 인증 자격 증명의 보고된 기간을 포함하여 외부 키 스토어의 작업 및 성능에 대한 자세한 Amazon CloudWatch 지표를 기록합니다. 이러한 지표를 사용하여 임박한 문제가 발생하기 전에 알리는 외부 키 스토어 및 CloudWatch 경보 작동을 위한 데이터 모델을 개발할 수 있습니다.

중요

AWS KMS는 CloudWatch 경보를 생성하여 외부 키 스토어 지표를 모니터링할 것을 권장합니다. 이러한 경보는 문제가 발생하기 전에 문제의 조기 징후를 알려줍니다.

모니터링 그래프

AWS KMS는 AWS KMS KMS 콘솔의 각 외부 키 스토어에 대한 세부 정보 페이지에 외부 키 스토어 CloudWatch 지표의 그래프를 표시합니다. 그래프의 데이터를 사용하여 오류의 원인을 찾고, 임박한 문제를 감지하고, 기준선을 설정하고, CloudWatch 경보 임계값을 세부 조정할 수 있습니다. 모니터링 그래프 해석 및 해당 데이터 사용에 대한 자세한 내용은 외부 키 저장소 모니터링 섹션을 참조하세요.

외부 키 스토어 및 KMS 키 표시

AWS KMS는 AWS KMS 콘솔의 외부 키 스토어와 DescribeCustomKeyStoresDescribeKey 작업에 대한 응답에서 외부 키 스토어 및 KMS 키에 대한 자세한 정보를 표시합니다. 외부 키 스토어의 연결 상태 및 KMS 키와 연결된 외부 키의 ID를 비롯하여 문제 해결에 사용할 수 있는 정보와 함께 외부 키 스토어 및 KMS 키에 대한 특수 필드 등이 표시됩니다. 세부 정보는 외부 키 저장소 보기을 참조하세요.

XKS 프록시 테스트 클라이언트

AWS KMS는 외부 키 스토어 프록시가 AWS KMS 외부 키 스토어 프록시 API 사양을 준수하는지 확인하는 오픈 소스 테스트 클라이언트를 제공합니다. 이 테스트 클라이언트를 사용하여 외부 키 스토어 프록시의 문제를 식별하고 해결할 수 있습니다.

구성 오류

외부 키 스토어를 생성할 때 프록시 인증 자격 증명, 프록시 URI 엔드포인트, 프록시 URI 경로VPC 엔드포인트 서비스 이름과 같은 외부 키 스토어의 구성을 포함하는 속성 값을 지정합니다. AWS KMS가 속성 값에서 오류를 감지하면 작업이 실패하고 잘못된 값을 나타내는 오류를 반환합니다.

잘못된 값을 수정하여 많은 구성 문제를 해결할 수 있습니다. 외부 키 스토어를 연결 해제하지 않고도 잘못된 프록시 URI 경로 또는 프록시 인증 자격 증명을 수정할 수 있습니다. 고유성 요구 사항을 포함하여 이러한 값의 정의는 사전 조건 수집 섹션을 참조하세요. 이러한 값 업데이트에 대한 지침은 외부 키 저장소 속성 편집 섹션을 참조하세요.

프록시 URI 경로 및 프록시 인증 자격 증명 값의 오류를 방지하려면 외부 키 스토어를 생성하거나 업데이트할 때 프록시 구성 파일을 AWS KMS 콘솔에 업로드합니다. 외부 키 스토어 프록시 또는 외부 키 관리자가 제공하는 프록시 URI 경로 및 프록시 인증 자격 증명 값이 있는 JSON 기반 파일입니다. AWS KMS 작업에는 프록시 구성 파일을 사용할 수 없지만 파일의 값을 사용하여 프록시의 값과 일치하는 API 요청에 대한 파라미터 값을 제공할 수 있습니다.

일반 구성 오류

예외: CustomKeyStoreInvalidStateException(CreateKey), KMSInvalidStateException(암호화 작업), XksProxyInvalidConfigurationException(관리 작업, CreateKey 제외)

연결 오류 코드: XKS_PROXY_INVALID_CONFIGURATION, XKS_PROXY_INVALID_TLS_CONFIGURATION

퍼블릭 엔드포인트 연결이 있는 외부 키 스토어의 경우 AWS KMS는 외부 키 스토어를 생성하고 업데이트할 때 속성 값을 테스트합니다. VPC 엔드포인트 서비스 연결이 있는 외부 키 스토어의 경우 AWS KMS는 외부 키 스토어를 연결하고 업데이트할 때 속성 값을 테스트합니다.

참고

비동기식인 ConnectCustomKeyStore 작업은 외부 키 스토어를 외부 키 스토어 프록시에 연결하려는 시도가 실패하더라도 성공할 수 있습니다. 이 경우 예외는 없지만 외부 키 스토어의 연결 상태는 Failed(실패)이며 연결 오류 코드는 오류 메시지를 설명합니다. 자세한 내용은 외부 키 스토어 연결 오류 단원을 참조하십시오.

AWS KMS가 속성 값에서 오류를 감지하면 작업이 실패하고 다음 오류 메시지 중 하나와 함께 XksProxyInvalidConfigurationException을 반환합니다.

외부 키 스토어 프록시가 잘못된 URI 경로 때문에 요청을 거부했습니다. 외부 키 스토어의 URI 경로를 확인하고 필요한 경우 업데이트합니다.
  • 프록시 URI 경로는 프록시 API에 대한 AWS KMS 요청의 기본 경로입니다. 이 경로가 올바르지 않으면 프록시에 대한 모든 요청이 실패합니다. 외부 키 스토어의 현재 프록시 URI 경로를 보려면 AWS KMS 콘솔 또는 DescribeCustomKeyStores 작업을 사용합니다. 올바른 프록시 URI 경로를 찾으려면 외부 키 스토어 프록시 설명서를 참조하세요. 프록시 URI 경로 값을 수정하는 방법에 대한 도움말은 외부 키 저장소 속성 편집 섹션을 참조하세요.

  • 외부 키 스토어 프록시의 프록시 URI 경로는 외부 키 스토어 프록시 또는 외부 키 관리자 업데이트에 따라 변경될 수 있습니다. 이러한 변경 사항에 대한 자세한 내용은 외부 키 스토어 프록시 또는 외부 키 관리자의 설명서를 참조하세요.

XKS_PROXY_INVALID_TLS_CONFIGURATION

AWS KMS가 외부 키 스토어 프록시에 대한 TLS 연결을 설정할 수 없습니다. 인증서를 포함하여 TLS 구성을 확인합니다.
  • 모든 외부 키 스토어 프록시에는 TLS 인증서가 필요합니다. 외부 키 스토어에 대해 지원되는 공인 인증 기관(CA)에서 TLS 인증서를 발급받아야 합니다. 지원되는 CA 목록은 AWS KMS 외부 키 스토어 프록시 API 사양의 Trusted Certificate Authorities(신뢰할 수 있는 인증 기관)를 참조하세요.

  • 퍼블릭 엔드포인트 연결의 경우 TLS 인증서의 주체 일반 이름(CN)은 외부 키 스토어 프록시에 대한 프록시 URI 엔드포인트의 도메인 이름과 일치해야 합니다. 예를 들어 퍼블릭 엔드포인트가 https://myproxy.xks.example.com인 경우 TLS, TLS 인증서의 CN은 myproxy.xks.example.com 또는 *.xks.example.com이어야 합니다.

  • VPC 엔드포인트 서비스 연결의 경우 TLS 인증서의 주체 일반 이름(CN)이 VPC 엔드포인트 서비스의 프라이빗 DNS 이름과 일치해야 합니다. 예를 들어 프라이빗 DNS 이름이 myproxy-private.xks.example.com인 경우 TLS 인증서의 CN은 myproxy-private.xks.example.com 또는 *.xks.example.com이어야 합니다.

  • TLS 인증서는 만료될 수 없습니다. TLS 인증서의 만료 날짜를 확인하려면 OpenSSL과 같은 SSL 도구를 사용합니다. 외부 키 스토어와 연결된 TLS 인증서의 만료 날짜를 모니터링하려면 XksProxyCertificateDaysToExpire CloudWatch 지표를 사용합니다. TLS 인증 만료일까지 남은 일수는 AWS KMS 콘솔의 Monitoring(모니터링) 섹션에도 나타납니다.

  • 퍼블릭 엔드포인트 연결을 사용하는 경우 SSL 테스트 도구를 사용하여 SSL 구성을 테스트합니다. 잘못된 인증서 연결로 인해 TLS 연결 오류가 발생할 수 있습니다.

VPC 엔드포인트 서비스 연결 구성 오류

예외: XksProxyVpcEndpointServiceNotFoundException, XksProxyVpcEndpointServiceInvalidConfigurationException

일반적인 연결 문제 외에도 VPC 엔드포인트 서비스 연결이 있는 외부 키 스토어를 생성, 연결 또는 업데이트하는 동안 다음과 같은 문제가 발생할 수 있습니다. AWS KMS는 외부 키 스토어를 생성, 연결업데이트하는 동안 VPC 엔드포인트 서비스 연결이 있는 외부 키 스토어의 속성 값을 테스트합니다. 구성 오류로 인해 관리 작업이 실패하면 다음 예외가 생성됩니다.

XksProxyVpcEndpointServiceNotFoundException

원인은 다음 중 하나일 수 있습니다.

  • VPC 엔드포인트 서비스 이름이 잘못되었습니다. 외부 키 스토어의 VPC 엔드포인트 서비스 이름이 올바르고 외부 키 스토어의 프록시 URI 엔드포인트 값과 일치하는지 확인합니다. VPC 엔드포인트 서비스 이름을 찾으려면 Amazon VPC 콘솔 또는 DescribeVpcEndpointServices 작업을 사용합니다. 기존 외부 키 스토어의 VPC 엔드포인트 서비스 이름과 프록시 URI 엔드포인트를 찾으려면 AWS KMS 콘솔 또는 DescribeCustomKeyStores 작업을 사용합니다. 세부 정보는 외부 키 저장소 보기을 참조하세요.

  • VPC 엔드포인트 서비스는 외부 키 스토어와 다른 AWS 리전에 있을 수 있습니다. VPC 엔드포인트 서비스와 외부 키 스토어가 동일한 리전에 있는지 확인합니다. (us-east-1과 같은 리전 이름의 외부 이름은 com.amazonaws.vpce.useast-1.vpce-svc-example과 같은 VPC 엔드포인트 서비스 이름의 일부입니다.) 외부 키 스토어의 VPC 엔드포인트 서비스에 대한 요구 사항 목록은 VPC 엔드포인트 서비스 섹션을 참조하세요. VPC 엔드포인트 서비스 또는 외부 키 스토어를 다른 리전으로 이동할 수 없습니다. 그러나 VPC 엔드포인트 서비스와 동일한 리전에서 새 외부 키 스토어를 생성할 수 있습니다. 자세한 내용은 VPC 엔드포인트 서비스 연결 구성외부 키 저장소 생성 섹션을 참조하세요.

  • AWS KMS는 VPC 엔드포인트 서비스에 대해 허용되는 보안 주체가 아닙니다. VPC 엔드포인트 서비스에 대한 Allow principals(보안 주체 허용) 목록에는 cks.kms.<region>.amazonaws.com 값(예: cks.kms.eu-west-3.amazonaws.com)이 포함되어야 합니다. 이 값을 추가하는 방법에 대한 지침은 AWS PrivateLink 가이드Manage permissions(권한 관리)를 참조하세요.

XksProxyVpcEndpointServiceInvalidConfigurationException

이 오류는 VPC 엔드포인트 서비스가 다음 요구 사항 중 하나를 충족하지 못할 때 발생합니다.

  • VPC에는 각각 다른 가용 영역에 있는 두 개 이상의 프라이빗 서브넷이 필요합니다. VPC에 서브넷을 추가하는 방법에 대한 도움말은 Amazon VPC 사용 설명서VPC에 서브넷 생성을 참조하세요.

  • VPC 엔드포인트 서비스 유형은 Gateway Load Balancer가 아닌 Network Load Balancer를 사용해야 합니다.

  • VPC 엔드포인트 서비스에 대해 수락이 필요하지 않아야 합니다(Acceptance required(수락 필요)는 false여야 함). 각 연결 요청을 수동으로 수락해야 하는 경우 AWS KMS는 VPC 엔드포인트 서비스를 사용하여 외부 키 스토어 프록시에 연결할 수 없습니다. 자세한 내용은 AWS PrivateLink 가이드Accept or 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(VPC 엔드포인트 서비스의 DNS 이름 관리)를 참조하세요.

  • 프라이빗 DNS 이름 도메인의 Domain verification status(도메인 확인 상태)는 verified여야 합니다. 프라이빗 DNS 이름 도메인의 확인 상태를 보고 업데이트하려면 5단계: 프라이빗 DNS 이름 도메인 확인 섹션을 참조하세요. 필수 텍스트 레코드를 추가한 후 업데이트된 확인 상태가 표시되는 데 몇 분 정도 걸릴 수 있습니다.

    참고

    프라이빗 DNS 도메인은 퍼블릭 도메인의 하위 도메인인 경우에만 확인할 수 있습니다. 그렇지 않으면 필요한 TXT 레코드를 추가한 후에도 프라이빗 DNS 도메인의 확인 상태가 변경되지 않습니다.

  • VPC 엔드포인트 서비스의 프라이빗 DNS 이름은 외부 키 스토어의 프록시 URI 엔드포인트 값과 일치해야 합니다. VPC 엔드포인트 서비스 연결이 있는 외부 키 스토어의 경우 프록시 URI 엔드포인트는 https:// 뒤에 VPC 엔드포인트 서비스의 프라이빗 DNS 이름이 와야 합니다. 프록시 URI 엔드포인트 값을 보려면 외부 키 저장소 보기 섹션을 참조하세요. 프록시 URI 엔드포인트 값을 변경하려면 외부 키 저장소 속성 편집 섹션을 참조하세요.

외부 키 스토어 연결 오류

외부 키 스토어 프록시에 외부 키 스토어를 연결하는 프로세스는 완료하는 데 5분가량 걸립니다. 빨리 실패하지 않는 한, ConnectCustomKeyStore 작업은 속성 없이 HTTP 200 응답 및 JSON 객체를 반환합니다. 하지만 이러한 초기 응답은 연결이 성공했음을 의미하지는 않습니다. 외부 키 스토어가 연결되어 있는지 파악하려면 해당 연결 상태를 확인합니다. 연결에 실패하면 외부 키 스토어의 연결 상태가 FAILED로 변경되고 AWS KMS가 실패 원인을 설명하는 연결 오류 코드를 반환합니다.

참고

사용자 지정 키 스토어의 연결 상태가 FAILED면 재연결을 시도하기에 앞서 사용자 지정 키 스토어를 연결 해제해야 합니다. 연결 상태가 FAILED이면 사용자 지정 키 스토어를 연결할 수 없습니다.

외부 키 스토어의 연결 상태를 보려면 다음을 수행하세요.

  • DescribeCustomKeyStores 응답에서 ConnectionState 요소의 값을 확인합니다.

  • AWS KMS 콘솔에서 외부 키 스토어 테이블에 Connection state(연결 상태)가 표시됩니다. 또한 각 외부 키 스토어의 세부 정보 페이지에서 General configuration(일반 구성) 섹션에 Connection state(연결 상태)가 표시됩니다.

연결 상태가 FAILED인 경우 연결 오류 코드는 오류를 설명하는 데 도움이 됩니다.

연결 오류 코드를 보려면 다음을 수행하세요.

  • DescribeCustomKeyStores 응답에서 ConnectionErrorCode 요소의 값을 확인합니다. 이 요소는 ConnectionStateFAILED인 경우에만 DescribeCustomKeyStores 응답에 나타납니다.

  • AWS KMS 콘솔에서 연결 오류 코드를 보려면 외부 키 스토어의 세부 정보 페이지에서 Failed(실패) 값 위로 마우스를 가져갑니다.

    사용자 지정 키 스토어 세부 정보 페이지의 연결 오류 코드

외부 키 스토어의 연결 오류 코드

다음 연결 오류 코드는 외부 키 스토어에 적용됩니다.

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

TLS 구성이 유효하지 않기 때문에 AWS KMS는 외부 키 스토어 프록시에 연결할 수 없습니다. 외부 키 스토어 프록시가 TLS 1.2 또는 1.3을 지원하는지 확인합니다. 또한 TLS 인증서가 만료되지 않았는지, XksProxyUriEndpoint 값의 호스트 이름과 일치하는지, Trusted Certificate Authorities(신뢰할 수 있는 인증 기관) 목록에 포함된 신뢰할 수 있는 인증 기관에서 서명했는지 확인합니다.

XKS_PROXY_NOT_REACHABLE

AWS KMS가 외부 키 스토어 프록시와 통신할 수 없습니다. XksProxyUriEndpointXksProxyUriPath가 올바른지 확인합니다. 외부 키 스토어 프록시용 도구를 사용하여 프록시가 활성 상태이고 해당 네트워크에서 사용 가능한지 확인합니다. 또한 외부 키 관리자 인스턴스가 제대로 작동하고 있는지 확인합니다. 프록시가 모든 외부 키 관리자 인스턴스를 사용할 수 없다고 보고하는 경우 이 연결 오류 코드와 함께 연결 시도가 실패합니다.

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 목록에는 리전에 대한 AWS KMS 서비스 보안 주체인 cks.kms.<region>.amazonaws.com(예: cks.kms.us-east-1.amazonaws.com)이 포함되어야 합니다.

  • 연결 요청 수락을 요구하지 않아야 합니다.

  • 프라이빗 DNS 이름이 있어야 합니다. VPC_ENDPOINT_SERVICE 연결이 있는 외부 키 스토어의 프라이빗 DNS 이름은 해당 AWS 리전에서 고유해야 합니다.

  • 프라이빗 DNS 이름 도메인의 확인 상태verified여야 합니다.

  • TLS 인증서는 엔드포인트에 도달할 수 있는 프라이빗 DNS 호스트 이름을 지정합니다.

XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND

AWS KMS가 외부 키 스토어 프록시와 통신하는 데 사용하는 VPC 엔드포인트 서비스를 찾을 수 없습니다. XksProxyVpcEndpointServiceName이 올바르고 AWS KMS 서비스 보안 주체에 Amazon VPC 엔드포인트 서비스에 대한 서비스 소비자 권한이 있는지 확인합니다.

지연 시간 및 제한 시간 오류

예외: CustomKeyStoreInvalidStateException(CreateKey), KMSInvalidStateException(암호화 작업), XksProxyUriUnreachableException(관리 작업)

연결 오류 코드: XKS_PROXY_NOT_REACHABLE, XKS_PROXY_TIMED_OUT

AWS KMS가 250밀리초 제한 시간 간격 내에 프록시에 연결할 수 없으면 예외를 반환합니다. CreateCustomKeyStoreUpdateCustomKeyStoreXksProxyUriUnreachableException을 반환합니다. 암호화 작업은 문제를 설명하는 오류 메시지와 함께 표준 KMSInvalidStateException을 반환합니다. ConnectCustomKeyStore가 실패하면 AWS KMS는 문제를 설명하는 연결 오류 코드를 반환합니다.

제한 시간 오류는 요청을 다시 시도하여 해결할 수 있는 일시적인 문제일 수 있습니다. 문제가 지속되면 외부 키 스토어 프록시가 활성 상태이고 네트워크에 연결되어 있으며 해당 프록시 URI 엔드포인트, 프록시 URI 경로 및 VPC 엔드포인트 서비스 이름(있는 경우)이 외부 키 스토어에서 올바른지 확인합니다. 또한 외부 키 관리자가 외부 키 스토어의 AWS 리전과 가까운지 확인합니다. 이러한 값을 업데이트해야 하는 경우 외부 키 저장소 속성 편집 섹션을 참조하세요.

지연 시간 패턴을 추적하려면 AWS KMS 콘솔의 Monitoring(모니터링) 섹션에서 XksProxyLatency CloudWatch 지표와 Average latency(평균 지연 시간) 그래프(해당 지표 기반)를 사용합니다. 외부 키 스토어 프록시는 지연 시간과 제한 시간을 추적하는 로그와 지표를 생성할 수도 있습니다.

XksProxyUriUnreachableException

AWS KMS가 외부 키 스토어 프록시와 통신할 수 없습니다. 일시적인 네트워크 문제일 수 있습니다. 이 오류가 반복적으로 표시되는 경우 외부 키 스토어 프록시가 활성 상태이고 네트워크에 연결되어 있는지, 해당 엔드포인트 URI가 외부 키 스토어에서 올바른지 확인합니다.
  • 외부 키 스토어 프록시가 250밀리초 제한 시간 간격 내에 AWS KMS 프록시 API 요청에 응답하지 않았습니다. 이는 일시적인 네트워크 문제나 프록시의 작동 또는 성능 문제를 나타낼 수 있습니다. 다시 시도해도 문제가 해결되지 않으면 외부 키 스토어 프록시 관리자에게 알리세요.

지연 시간 및 제한 시간 오류는 종종 연결 실패로 나타납니다. ConnectCustomKeyStore 작업에 실패하면 외부 키 스토어의 연결 상태가 FAILED로 변경되고 AWS KMS가 오류를 설명하는 연결 오류 코드를 반환합니다. 연결 오류 코드 목록과 오류 해결을 위한 제안 사항은 외부 키 스토어의 연결 오류 코드 섹션을 참조하세요. 모든 사용자 지정 키 스토어외부 키 스토어의 연결 코드 목록은 외부 키 스토어에 적용됩니다. 다음 연결 오류는 지연 시간 및 제한 시간과 관련이 있습니다.

XKS_PROXY_NOT_REACHABLE

-또는-

CustomKeyStoreInvalidStateException, KMSInvalidStateException, XksProxyUriUnreachableException

AWS KMS가 외부 키 스토어 프록시와 통신할 수 없습니다. 외부 키 스토어 프록시가 활성 상태이고 네트워크에 연결되어 있는지, 해당 URI 경로와 엔드포인트 URI 또는 VPC 서비스 이름이 외부 키 스토어에서 올바른지 확인합니다.

이 오류는 다음과 같은 이유로 발생할 수 있습니다.

  • 외부 키 스토어 프록시가 활성 상태가 아니거나 네트워크에 연결되어 있지 않습니다.

  • 외부 키 스토어 구성의 프록시 URI 엔드포인트, 프록시 URI 경로 또는 VPC 엔드포인트 서비스 이름(해당하는 경우) 값에 오류가 있습니다. 외부 키 스토어 구성을 보려면 DescribeCustomKeyStores 작업을 사용하거나 AWS KMS 콘솔에서 외부 키 스토어의 세부 정보 페이지를 봅니다.

  • AWS KMS와 외부 키 스토어 프록시 사이의 네트워크 경로에 포트 오류와 같은 네트워크 구성 오류가 있을 수 있습니다. AWS KMS는 포트 443에서 외부 키 스토어 프록시와 통신합니다. 이 값은 구성할 수 없습니다.

  • 외부 키 스토어 프록시가 GetHealthStatus 응답에서 모든 외부 키 관리자 인스턴스가 UNAVAILABLE이라고 보고하면 XKS_PROXY_NOT_REACHABLEConnectionErrorCode와 함께 ConnectCustomKeyStore 작업이 실패합니다. 도움말은 외부 키 관리자 설명서를 참조하세요.

  • 이 오류는 외부 키 스토어가 있는 AWS 리전과 외부 키 관리자 간의 물리적 거리가 멀기 때문에 발생할 수 있습니다. AWS 리전과 외부 키 관리자 사이의 ping 지연 시간(네트워크 왕복 시간(RTT))은 35밀리초를 넘지 않아야 합니다. 외부 키 관리자에 더 가까운 AWS 리전에서 외부 키 스토어를 생성하거나 외부 키 관리자를 AWS 리전에 더 가까운 데이터 센터로 이동해야 할 수 있습니다.

XKS_PROXY_TIMED_OUT

-또는-

CustomKeyStoreInvalidStateException, KMSInvalidStateException, XksProxyUriUnreachableException

외부 키 스토어 프록시가 제시간에 응답하지 않았기 때문에 AWS KMS가 요청을 거부했습니다. 요청을 다시 시도하세요. 이 오류가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 보고하세요.

이 오류는 다음과 같은 이유로 발생할 수 있습니다.

  • 이 오류는 외부 키 관리자와 외부 키 스토어 프록시 간의 물리적 거리가 멀기 때문에 발생할 수 있습니다. 가능한 경우 외부 키 스토어 프록시를 외부 키 관리자에 더 가깝게 이동합니다.

  • 프록시가 AWS KMS의 요청 볼륨과 빈도를 처리하도록 설계되지 않은 경우 제한 시간 오류가 발생할 수 있습니다. CloudWatch 지표가 지속적인 문제를 나타내는 경우 외부 키 스토어 프록시 관리자에게 알리세요.

  • 외부 키 관리자와 외부 키 스토어에 대한 Amazon VPC 간의 연결이 제대로 작동하지 않는 경우 제한 시간 오류가 발생할 수 있습니다. AWS Direct Connect를 사용하는 경우 VPC와 외부 키 관리자가 효과적으로 통신할 수 있는지 확인합니다. 문제를 해결하는 방법에 대한 도움말은 AWS Direct Connect 사용 설명서의 AWS Direct Connect 문제 해결을 참조하세요.

XKS_PROXY_TIMED_OUT

-또는-

CustomKeyStoreInvalidStateException, KMSInvalidStateException, XksProxyUriUnreachableException

외부 키 스토어 프록시가 할당된 시간 내에 요청에 응답하지 않았습니다. 요청을 다시 시도하세요. 이 오류가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 보고하세요.
  • 이 오류는 외부 키 관리자와 외부 키 스토어 프록시 간의 물리적 거리가 멀기 때문에 발생할 수 있습니다. 가능한 경우 외부 키 스토어 프록시를 외부 키 관리자에 더 가깝게 이동합니다.

인증 자격 증명 오류

예외: CustomKeyStoreInvalidStateException(CreateKey), KMSInvalidStateException(암호화 작업), XksProxyIncorrectAuthenticationCredentialException(CreateKey 이외의 관리 작업)

외부 키 스토어 프록시에서 AWS KMS에 대한 인증 자격 증명을 설정하고 유지합니다. 그런 다음 외부 키 스토어를 생성할 때 AWS KMS에 자격 증명 값을 알려줍니다. 인증 자격 증명을 변경하려면 외부 키 스토어 프록시에서 변경합니다. 그런 다음 외부 키 스토어에 대한 자격 증명을 업데이트합니다. 프록시가 자격 증명을 교체하는 경우 외부 키 스토어에 대한 자격 증명을 업데이트해야 합니다.

외부 키 스토어 프록시가 외부 키 스토어에 대한 프록시 인증 자격 증명으로 서명된 요청을 인증하지 않는 경우 효과는 요청에 따라 다릅니다.

  • CreateCustomKeyStoreUpdateCustomKeyStoreXksProxyIncorrectAuthenticationCredentialException과 함께 실패합니다.

  • ConnectCustomKeyStore는 성공하지만 연결은 실패합니다. 연결 상태는 FAILED이고 연결 오류 코드는 INVALID_CREDENTIALS입니다. 세부 정보는 외부 키 스토어 연결 오류을 참조하세요.

  • 암호화 작업은 외부 키 저장소의 모든 외부 구성 오류 및 연결 상태 오류에 대하여 KMSInvalidStateException를 반환합니다. 함께 제공되는 오류 메시지에 문제가 설명되어 있습니다.

외부 키 스토어 프록시가 AWS KMS를 인증할 수 없기 때문에 요청을 거부했습니다. 외부 키 스토어의 자격 증명을 확인하고 필요한 경우 업데이트합니다.

이 오류는 다음과 같은 이유로 발생할 수 있습니다.

  • 외부 키 스토어의 액세스 키 ID 또는 보안 액세스 키가 외부 키 스토어 프록시에 설정된 값과 일치하지 않습니다.

    이 오류를 해결하려면 외부 키 스토어의 프록시 인증 자격 증명을 업데이트합니다. 외부 키 스토어를 연결 해제하지 않고 이 변경을 수행할 수 있습니다.

  • AWS KMS와 외부 키 스토어 프록시 간의 역방향 프록시는 SigV4 서명을 무효화하는 방식으로 HTTP 헤더를 조작할 수 있습니다. 이 오류를 수정하려면 프록시 관리자에게 알리세요.

키 상태 오류

예외: KMSInvalidStateException

KMSInvalidStateException은 사용자 지정 키 스토어의 KMS 키에 대해 두 가지 다른 용도로 사용됩니다.

  • CancelKeyDeletion과 같은 관리 작업이 실패하고 이 예외를 반환하면 KMS 키의 키 상태가 작업과 호환되지 않는 것입니다.

  • 사용자 지정 키 스토어의 KMS 키에 대한 암호화 작업KMSInvalidStateException과 함께 실패하면 KMS 키의 키 상태에 문제가 있는 것일 수 있습니다. 그러나 AWS KMS 암호화 작업은 외부 키 스토어의 모든 외부 구성 오류 및 연결 상태 오류에 대하여 KMSInvalidStateException을 반환합니다. 문제를 식별하려면 예외와 함께 제공되는 오류 메시지를 사용합니다.

AWS KMS API 작업에 필요한 키 상태를 찾으려면 AWS KMS 키의 키 상태 세션을 참조하세요. KMS 키의 키 상태를 확인하려면 (고객 관리형 키 페이지에서 KMS 키의 상태 필드를 확인합니다. 또는 DescribeKey 작업을 사용해 응답의 KeyState 요소를 확인합니다. 세부 정보는 키 식별 및 보기을 참조하세요.

참고

외부 키 스토어에 있는 KMS 키의 키 상태는 연결된 외부 키의 상태에 대해 아무 것도 나타내지 않습니다. 외부 키 상태에 대한 자세한 내용을 보려면 외부 키 관리자와 외부 키 스토어 프록시 도구를 사용하세요.

CustomKeyStoreInvalidStateException은 KMS 키의 키 상태가 아니라 외부 키 스토어의 연결 상태를 나타냅니다.

KMS 키의 키 상태가 Unavailable 또는 PendingDeletion이므로 사용자 지정 스토어의 KMS 키에 대한 암호화 작업이 실패할 수 있습니다. (비활성화된 키에서는 DisabledException이 반환됩니다.)

  • KMS 키는 AWS KMS 콘솔에서 또는 DisableKey 작업을 사용하여 의도적으로 KMS 키를 비활성화하는 경우에만 Disabled 키 상태가 됩니다. KMS 키가 비활성화된 동안에는 키를 보고 관리할 수 있지만 암호화 작업에 사용할 수는 없습니다. 이 문제를 해결하려면 키를 활성화합니다. 세부 정보는 KMS 키 활성화 및 비활성화을 참조하세요.

  • KMS 키는 외부 키 스토어가 외부 키 스토어 프록시에서 연결 해제되는 경우 Unavailable 키 상태가 됩니다. 사용 불가 상태인 KMS 키를 수정하려면 외부 키 스토어를 다시 연결합니다. 외부 키 스토어가 다시 연결되고 나면 외부 키 스토어의 KMS 키 상태가 이전 상태(Enabled 또는 Disabled)로 자동 복구됩니다.

    KMS 키는 삭제 예약이 되어 있고 대기 기간에 있는 경우 PendingDeletion 키 상태가 됩니다. 삭제 보류 중인 KMS 키의 키 상태 오류는 키가 암호화에 사용되고 있거나 복호화에 필요하기 때문에 삭제해서는 안 됨을 나타냅니다. KMS 키를 다시 활성화하려면 예약된 삭제를 취소한 다음 키를 활성화합니다. 세부 정보는 키 삭제 예약을 참조하세요.

복호화 오류

예외: KMSInvalidStateException

외부 키 스토어의 KMS 키를 사용하는 Decrypt 작업이 실패하는 경우 AWS KMS에서는 암호화 작업이 외부 키 스토어 모든 외부 구성 오류 및 연결 상태 오류에 대하여 사용하는 표준 KMSInvalidStateException을 반환합니다. 오류 메시지가 문제를 나타냅니다.

이중 암호화를 사용하여 암호화된 사이퍼텍스트를 복호화하기 위해 외부 키 관리자는 먼저 외부 키를 사용하여 사이퍼텍스트의 외부 계층을 복호화합니다. 그런 다음 AWS KMS는 KMS 키의 AWS KMS 키 구성 요소를 사용하여 사이퍼텍스트의 내부 계층을 복호화합니다. 유효하지 않거나 손상된 사이퍼텍스트는 외부 키 관리자 또는 AWS KMS에 의해 거부될 수 있습니다.

복호화가 실패하면 KMSInvalidStateException과 함께 다음 오류 메시지가 나타납니다. 요청의 사이퍼텍스트 또는 선택적 암호화 컨텍스트에 문제가 있는 것입니다.

외부 키 스토어 프록시가 지정된 사이퍼텍스트나 추가 인증 데이터가 손상 또는 누락되었거나 유효하지 않기 때문에 요청을 거부했습니다.
  • 외부 키 스토어 프록시 또는 외부 키 관리자가 사이퍼텍스트 또는 해당 암호화 컨텍스트가 유효하지 않다고 보고하면 일반적으로 AWS KMS로 전송된 Decrypt 요청의 사이퍼텍스트 또는 암호화 컨텍스트에 문제가 있는 것입니다. Decrypt 작업의 경우 AWS KMS는 Decrypt 요청에서 수신한 것과 동일한 사이퍼텍스트 및 암호화 컨텍스트를 프록시에 보냅니다.

    이 오류는 플립드 비트와 같은 전송 중 네트워킹 문제로 인해 발생할 수 있습니다. Decrypt 요청을 다시 시도하세요. 문제가 지속되면 사이퍼텍스트가 변경되거나 손상되지 않았는지 확인합니다. 또한 AWS KMS에 대한 Decrypt 요청의 암호화 컨텍스트가 데이터를 암호화한 요청의 암호화 컨텍스트와 일치하는지 확인합니다.

암호 복호화를 위해 외부 키 스토어 프록시가 제출한 사이퍼텍스트 또는 암호화 컨텍스트가 손상되었거나 누락되었거나 유효하지 않습니다.
  • AWS KMS가 프록시에서 수신한 사이퍼텍스트를 거부하면 외부 키 관리자 또는 프록시가 AWS KMS에 유효하지 않거나 손상된 사이퍼텍스트를 반환한 것입니다.

    이 오류는 플립드 비트와 같은 전송 중 네트워킹 문제로 인해 발생할 수 있습니다. Decrypt 요청을 다시 시도하세요. 문제가 지속되면 외부 키 관리자가 제대로 작동하는지, 외부 키 스토어 프록시가 외부 키 관리자로부터 받은 사이퍼텍스트를 AWS KMS에 반환하기 전에 변경하지 않는지 확인합니다.

외부 키 오류

외부 키는 KMS 키의 외부 키 구성 요소 역할을 하는 외부 키 관리자의 암호화 키입니다. AWS KMS는 외부 키에 직접 액세스할 수 없습니다. 외부 키 스토어 프록시를 통해 외부 키 관리자에게 외부 키를 사용하여 데이터를 암호화하거나 사이퍼텍스트를 복호화하도록 요청해야 합니다.

외부 키 스토어에서 KMS 키를 생성할 때 외부 키 관리자에서 외부 키의 ID를 지정합니다. KMS 키를 생성한 후에는 외부 키 ID를 변경할 수 없습니다. KMS 키 관련 문제를 방지하기 위해 CreateKey 작업은 외부 키의 ID와 구성을 확인하도록 외부 키 스토어 프록시에 요청합니다. 외부 키가 KMS 키와 함께 사용하기 위한 요구 사항을 충족하지 않는 경우 문제를 식별하는 예외 및 오류 메시지와 함께 CreateKey 작업이 실패합니다.

그러나 KMS 키가 생성된 후 문제가 발생할 수 있습니다. 외부 키 문제로 인해 암호화 작업이 실패하면 작업이 실패하고 문제를 나타내는 오류 메시지와 함께 KMSInvalidStateException이 반환됩니다.

외부 키에 대한 CreateKey 오류

예외: XksKeyAlreadyInUseException, XksKeyNotFoundException, XksKeyInvalidConfigurationException

CreateKey 작업은 External key ID(외부 키 ID)(콘솔) 또는 XksKeyId(API) 파라미터에 제공한 외부 키의 ID와 속성을 확인하려고 시도합니다. 이 방법은 KMS 키와 함께 외부 키를 사용하려고 시도하기 전에 조기에 오류를 감지하도록 설계되었습니다.

외부 키 사용 중

외부 키 스토어의 각 KMS 키는 다른 외부 키를 사용해야 합니다. CreateKey는 KMS 키의 외부 키 ID(XksKeyId)가 외부 키 스토어에서 고유하지 않음을 인식하면 XksKeyAlreadyInUseException과 함께 실패합니다.

동일한 외부 키에 대해 여러 ID를 사용하는 경우 CreateKey는 중복을 인식하지 않습니다. 그러나 외부 키가 동일한 KMS 키는 AWS KMS KMS 키 구성 요소와 메타데이터가 다르기 때문에 상호 운용이 불가능합니다.

외부 키를 찾을 수 없음

외부 키 스토어 프록시가 KMS 키에 대한 외부 키 ID(XksKeyId)를 사용하여 외부 키를 찾을 수 없다고 보고하면 CreateKey 작업이 실패하고 다음 오류 메시지와 함께 XksKeyNotFoundException을 반환합니다.

외부 키 스토어 프록시가 외부 키를 찾을 수 없기 때문에 요청을 거부했습니다.

이 오류는 다음과 같은 이유로 발생할 수 있습니다.

  • KMS 키의 외부 키(XksKeyId) ID(XksKeyId)가 유효하지 않을 수 있습니다. 외부 키 프록시가 외부 키를 식별하는 데 사용하는 ID를 찾으려면 외부 키 스토어 프록시 또는 외부 키 관리자 설명서를 참조하세요.

  • 외부 키가 외부 키 관리자에서 삭제되었을 수 있습니다. 조사하려면 외부 키 관리자 도구를 사용합니다. 외부 키가 영구적으로 삭제된 경우 KMS 키와 함께 다른 외부 키를 사용합니다. 외부 키의 목록 또는 요구 사항은 외부 키 스토어의 KMS 키 요구 사항 섹션을 참조하세요.

외부 키 요구 사항이 충족되지 않음

외부 키 스토어 프록시에서 외부 키가 KMS 키와 함께 사용하기 위한 요구 사항을 충족하지 않는다고 보고하면 CreateKey 작업이 실패하고 다음 오류 메시지 중 하나와 함께 XksKeyInvalidConfigurationException을 반환합니다.

외부 키의 키 사양은 AES_256이어야 합니다. 지정된 외부 키의 키 사양은 <key-spec>.입니다.
  • 외부 키는 키 사양이 AES_256인 256비트 대칭 암호화 키여야 합니다. 지정된 외부 키가 다른 유형인 경우 이 요구 사항을 충족하는 외부 키의 ID를 지정합니다.

외부 키의 상태가 ENABLED여야 합니다. 지정된 외부 키의 상태는 <status>여야 합니다.
  • 외부 키 관리자에서 외부 키를 활성화해야 합니다. 지정된 외부 키가 활성화되지 않은 경우 외부 키 관리자 도구를 사용하여 활성화하거나 활성화된 외부 키를 지정합니다.

외부 키의 키 사용에는 ENCRYPT와 DECRYPT가 포함되어야 합니다. 지정된 외부 키의 키 사용은 <key-usage>입니다.
  • 외부 키 관리자에서 암호화와 복호화를 위해 외부 키를 구성해야 합니다. 지정된 외부 키에 이러한 작업이 포함되지 않은 경우 외부 키 관리자 도구를 사용하여 작업을 변경하거나 다른 외부 키를 지정합니다.

외부 키에 대한 암호화 작업 오류

예외: KMSInvalidStateException

외부 키 스토어 프록시가 KMS 키와 연결된 외부 키를 찾을 수 없거나 외부 키가 KMS 키와 함께 사용하기 위한 요구 사항을 충족하지 못하면 암호화 작업이 실패합니다.

암호화 작업 중 감지되는 외부 키 문제는 KMS 키를 생성하기 전에 감지된 외부 키 문제보다 해결하기 더 어렵습니다. KMS 키를 생성한 후에는 외부 키 ID를 변경할 수 없습니다. KMS 키가 아직 데이터를 암호화하지 않은 경우 KMS 키를 삭제하고 다른 외부 키 ID로 새 키를 생성할 수 있습니다. 그러나 KMS 키로 생성된 사이퍼텍스트는 다른 KMS 키(동일한 외부 키가 있는 키라 하더라도)로 복호화할 수 없습니다. 키에 다른 키 메타데이터와 다른 AWS KMS 구성 요소가 있기 때문입니다. 대신 가능한 한 외부 키 관리자 도구를 사용하여 외부 키 관련 문제를 해결하세요.

외부 키 스토어 프록시가 외부 키에 문제가 있다고 보고하면 암호화 작업은 문제를 식별하는 오류 메시지와 함께 KMSInvalidStateException을 반환합니다.

외부 키를 찾을 수 없음

외부 키 스토어 프록시가 KMS 키에 대한 외부 키 ID(XksKeyId)를 사용하여 외부 키를 찾을 수 없다고 보고하면 암호화 작업이 다음 오류 메시지와 함께 KMSInvalidStateException을 반환합니다.

외부 키 스토어 프록시가 외부 키를 찾을 수 없기 때문에 요청을 거부했습니다.

이 오류는 다음과 같은 이유로 발생할 수 있습니다.

  • KMS 키의 외부 키 ID(XksKeyId)가 더 이상 유효하지 않습니다.

    KMS 키와 연결된 외부 키 ID를 찾으려면 KMS 키의 세부 정보를 봅니다. 외부 키 프록시가 외부 키를 식별하는 데 사용하는 ID를 찾으려면 외부 키 스토어 프록시 또는 외부 키 관리자 설명서를 참조하세요.

    AWS KMS는 외부 키 스토어에서 KMS 키를 생성할 때 외부 키 ID를 확인합니다. 그러나 특히 외부 키 ID 값이 별칭이거나 변경 가능한 이름인 경우 ID가 무효화될 수 있습니다. 기존 KMS 키와 연결된 외부 키 ID는 변경할 수 없습니다. KMS 키로 암호화된 사이퍼텍스트를 복호화하려면 외부 키를 기존 외부 키 ID와 다시 연결해야 합니다.

    아직 KMS 키를 사용하여 데이터를 암호화하지 않은 경우 유효한 외부 키 ID로 새 KMS 키를 생성할 수 있습니다. 그러나 KMS 키로 사이퍼텍스트를 생성한 경우 동일한 외부 키를 사용하더라도 다른 KMS 키를 사용하여 사이퍼텍스트를 복호화할 수 없습니다.

  • 외부 키가 외부 키 관리자에서 삭제되었을 수 있습니다. 조사하려면 외부 키 관리자 도구를 사용합니다. 가능하면 외부 키 관리자의 사본 또는 백업에서 키 구성 요소를 복구해 봅니다. 외부 키가 영구적으로 삭제되면 연결된 KMS 키로 암호화된 사이퍼텍스트를 복구할 수 없습니다.

외부 키 구성 오류

외부 키 스토어 프록시에서 외부 키가 KMS 키와 함께 사용하기 위한 요구 사항을 충족하지 않는다고 보고하면 암호화 작업이 다음 오류 메시지 중 하나와 함께 KMSInvalidStateException을 반환합니다.

외부 키가 요청된 작업을 지원하지 않기 때문에 외부 키 스토어 프록시가 요청을 거부했습니다.
  • 외부 키가 암호화와 복호화를 모두 지원해야 합니다. 키 사용에 암호화와 복호화가 포함되지 않은 경우 외부 키 관리자 도구를 사용하여 키 사용을 변경합니다.

외부 키 관리자에서 외부 키가 활성화되지 않았기 때문에 외부 키 스토어 프록시가 요청을 거부했습니다.
  • 외부 키를 활성화하고 외부 키 관리자에서 사용할 수 있어야 합니다. 외부 키의 상태가 Enabled가 아닌 경우 외부 키 관리자 도구를 사용하여 외부 키를 활성화합니다.

프록시 문제

예외:

CustomKeyStoreInvalidStateException (CreateKey), KMSInvalidStateException(암호화 작업), UnsupportedOperationException, XksProxyUriUnreachableException, XksProxyInvalidResponseException(CreateKey 이외의 관리 작업)

외부 키 스토어 프록시는 AWS KMS와 외부 키 관리자 간의 모든 통신을 조정합니다. 또한 일반 AWS KMS 요청을 외부 키 관리자가 이해할 수 있는 형식으로 변환합니다. 외부 키 스토어 프록시가 AWS KMS 외부 키 스토어 프록시 API 사양을 준수하지 않거나 제대로 작동하지 않거나 AWS KMS와 통신할 수 없는 경우 외부 키 스토어에서 KMS 키를 생성하거나 사용할 수 없습니다.

많은 오류가 외부 키 스토어 아키텍처에서의 중요한 역할 때문에 외부 키 스토어 프록시를 언급하지만 이러한 문제는 외부 키 관리자 또는 외부 키에서 발생할 수 있습니다.

이 섹션의 문제는 외부 키 스토어 프록시의 설계 또는 작업 문제와 관련이 있습니다. 이러한 문제를 해결하려면 프록시 소프트웨어를 변경해야 할 수 있습니다. 프록시 관리자에게 문의하세요. 프록시 문제 진단에 도움이 되도록 AWS KMS는 외부 키 스토어 프록시가 AWS KMS 외부 키 스토어 프록시 API 사양을 준수하는지 확인하는 오픈 소스 테스트 클라이언트인 XKS 프록시 테스트 클라이언트를 제공합니다.

CustomKeyStoreInvalidStateException, KMSInvalidStateException 또는 XksProxyUriUnreachableException

외부 키 스토어 프록시가 비정상 상태입니다. 이 메시지가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 알리세요.
  • 이 오류는 외부 키 스토어 프록시의 운영 문제 또는 소프트웨어 오류를 나타낼 수 있습니다. 각 오류를 생성한 AWS KMS API 작업에 대한 CloudTrail 로그 항목을 찾을 수 있습니다. 이 오류는 작업을 다시 시도하여 해결할 수 있습니다. 그러나 이 오류가 지속되면 외부 키 스토어 프록시 관리자에게 알리세요.

  • 외부 키 스토어 프록시가 GetHealthStatus 응답에서 모든 외부 키 관리자 인스턴스가 UNAVAILABLE이라고 보고하면 이 예외와 함께 외부 키 스토어를 생성하거나 업데이트하려는 시도가 실패합니다. 이 오류가 지속되면 외부 키 관리자 설명서를 참조하세요.

CustomKeyStoreInvalidStateException, KMSInvalidStateException 또는 XksProxyInvalidResponseException

AWS KMS는 외부 키 스토어 프록시의 응답을 해석할 수 없습니다. 이 오류가 반복적으로 표시되면 외부 키 스토어 프록시 관리자에게 문의하세요.
  • 프록시가 AWS KMS가 구문 분석하거나 해석할 수 없는 정의되지 않은 응답을 반환하면 AWS KMS 작업이 이 예외를 생성합니다. 이 오류는 일시적인 외부 문제나 산발적인 네트워크 오류로 인해 가끔 발생할 수 있습니다. 그러나 지속되면 외부 키 스토어 프록시가 AWS KMS 외부 키 스토어 프록시 API 사양을 준수하지 않는 것일 수 있습니다. 외부 키 스토어 관리자 또는 공급업체에 알리세요.

CustomKeyStoreInvalidStateException, KMSInvalidStateException 또는 UnsupportedOperationException

외부 키 스토어 프록시가 요청된 작업을 암호화 작업을 지원하지 않기 때문에 요청을 거부했습니다.

  • 외부 키 스토어 프록시는 AWS KMS 외부 키 스토어 프록시 API 사양에 정의된 모든 프록시 API를 지원해야 합니다. 이 오류는 프록시가 요청과 관련된 작업을 지원하지 않음을 나타냅니다. 외부 키 스토어 관리자 또는 공급업체에 알리세요.

프록시 권한 부여 문제

예외: CustomKeyStoreInvalidStateException, KMSInvalidStateException

일부 외부 키 스토어 프록시는 외부 키 사용에 대한 권한 부여 요구 사항을 구현합니다. 외부 키 스토어 프록시는 특정 사용자가 특정 조건에서 특정 작업을 요청할 수 있도록 하는 권한 부여 체계를 설계하고 구현하는 데 허용되지만 필수는 아닙니다. 예를 들어 프록시를 사용하면 사용자가 특정 외부 키로 암호화할 수 있지만 복호화할 수는 없습니다. 자세한 내용은 외부 키 스토어 프록시 권한 부여(선택 사항) 단원을 참조하십시오.

프록시 권한 부여는 AWS KMS가 프록시에 대한 요청에 포함하는 메타데이터를 기반으로 합니다. awsSourceVpcawsSourceVpce 필드는 요청이 VPC 엔드포인트에서 발생하고 호출자가 KMS 키와 동일한 계정에 있는 경우에만 메타데이터에 포함됩니다.

"requestMetadata": { "awsPrincipalArn": string, "awsSourceVpc": string, // optional "awsSourceVpce": string, // optional "kmsKeyArn": string, "kmsOperation": string, "kmsRequestId": string, "kmsViaService": string // optional }

권한 부여 실패로 인해 프록시가 요청을 거부하면 관련 AWS KMS 작업이 실패합니다. CreateKeyCustomKeyStoreInvalidStateException을 반환합니다. AWS KMS 암호화 작업은 KMSInvalidStateException을 반환합니다. 둘 다 다음 오류 메시지를 사용합니다.

외부 키 스토어 프록시가 작업에 대한 액세스를 거부했습니다. 사용자와 외부 키 모두에 이 작업에 대한 권한이 있는지 확인하고 요청을 다시 시도하세요.
  • 오류를 해결하려면 외부 키 관리자 또는 외부 키 스토어 프록시 도구를 사용하여 인증에 실패한 이유를 확인합니다. 그런 다음 무단 요청을 유발한 절차를 업데이트하거나 외부 키 스토어 프록시 도구를 사용하여 권한 부여 정책을 업데이트합니다. AWS KMS에서는 이 오류를 해결할 수 없습니다.