기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 키 스토리지 공급자(KSP)를 AWS CloudHSM 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션
이 주제에서는 [KSP(Key Storage Provider)](ksp-library.md)를 AWS CloudHSM 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션하는 방법을 설명합니다. AWS CloudHSM 클라이언트 SDK의 최신 버전은 5.16입니다. 마이그레이션 이점에 대한 자세한 내용은 [AWS CloudHSM 클라이언트 SDK 5의 이점](client-sdk-5-benefits.md) 섹션을 참조하세요.
에서는 AWS CloudHSM 클라이언트 소프트웨어 개발 키트(SDK)를 AWS CloudHSM사용하여 암호화 작업을 수행합니다. 클라이언트 SDK 5는 새로운 기능과 플랫폼 지원 업데이트를 수신하는 기본 SDK입니다.
모든 공급자에 대한 마이그레이션 지침은 [AWS CloudHSM 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션](client-sdk-migration.md) 섹션을 참조하세요.
## 클라이언트 SDK 5로 마이그레이션
1. 클라이언트 SDK 3용 클라이언트 대몬을 중지합니다.
```
PS C:\> Stop-Service "AWS CloudHSM Client"
```
1. Windows Server 인스턴스에 클라이언트 SDK 5 KSP(Key Storage Provider)를 설치합니다. 지침은 [AWS CloudHSM 클라이언트 SDK 5용 키 스토리지 공급자(KSP) 설치](ksp-library-install.md) 섹션을 참조하세요.
1. 새 구성 파일 형식과 명령줄 부트스트래핑 도구를 사용하여 클라이언트 SDK 5 KSP(Key Storage Provider)를 구성합니다. 지침은 [클라이언트 SDK 부트스트랩](cluster-connect.md#connect-how-to) 섹션을 참조하세요.
1. AWS CloudHSM 클라이언트 SDK 5용 키 스토리지 공급자(KSP)에는 SDK3에서 생성된 키 참조 파일을 지원하는 SDK3 호환성 모드가 포함되어 있습니다. 자세한 내용은 [용 키 스토리지 공급자(KSP)의 SDK3 호환성 모드 AWS CloudHSM](ksp-library-configs-sdk3-compatibility-mode.md) 단원을 참조하십시오.
**참고**
클라이언트 SDK 3에서 생성한 키 참조 파일을 클라이언트 SDK 5와 함께 사용할 때 SDK 3 호환성 모드를 활성화해야 합니다.
## 새 Windows Server 인스턴스로 마이그레이션
1. 새 Windows Server 인스턴스에서 [클라이언트 SDK 5로 마이그레이션](#ksp-migrate-steps)의 모든 단계를 완료합니다.
1.
**기존 키 참조 파일 확인**
원래 Windows Server 인스턴스에서 `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`의 키 참조 파일을 확인합니다.
+ 키 참조 파일이 있는 경우 `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP`의 모든 내용(`GlobalPartition` 포함)을 새 Windows Server 인스턴스의 동일한 디렉터리 경로에 복사합니다. 기본 디렉터리가 없다면 생성합니다.
+ 키 참조 파일이 없는 경우 새 Windows Server 인스턴스에서 `cloudhsm-cli key generate-file --encoding ksp-key-reference`를 사용하여 생성합니다. 지침은 [KSP 키 참조 생성(Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference) 섹션을 참조하세요.
1.
**루트 인증서 확인**
신뢰할 수 있는 루트 인증 기관에서 루트 인증서를 확인합니다.
```
PS C:\Users\Administrator\Desktop> certutil -store Root
Root "Trusted Root Certification Authorities"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Issuer: CN=MYRootCA
Signature matches Public Key
Root Certificate: Subject matches Issuer
Cert Hash(sha1): cert-hash
No key provider information
Cannot find the certificate and private key for decryption.
CertUtil: -store command completed successfully.
```
**참고**
다음 단계에서 사용할 인증서 일련 번호를 기록해 둡니다.
1.
**루트 인증서 내보내기**
루트 인증서를 파일로 내보냅니다.
```
certutil -store Root certificate-serial-number root-certificate-name.cer
```
1.
**HSM 백엔드 인증서 확인**
개인 인증서 저장소에서 HSM 백엔드 인증서를 확인합니다.
```
PS C:\Users\Administrator\Desktop> certutil -store My
my "Personal"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US
Non-root Certificate
Cert Hash(sha1): cert-hash
Key Container = key-container-name
Provider = Cavium Key Storage Provider
Private key is NOT exportable
Encryption test passed
CertUtil: -store command completed successfully.
```
**참고**
다음 단계에서 사용할 인증서 일련 번호를 기록해 둡니다.
1.
**HSM 백엔드 인증서 내보내기**
HSM 백엔드 인증서를 파일로 내보냅니다.
```
certutil -store My certificate-serial-number signed-certificate-name.cer
```
1.
**루트 인증서 가져오기**
새 Windows 인스턴스에서 다음을 수행합니다.
1. 루트 CA 파일을 새 Windows 인스턴스에 복사
1. 인증서 가져오기
```
certutil -addstore Root root-certificate-name.cer
```
1.
**루트 인증서 설치 확인**
루트 인증서가 올바르게 설치되었는지 확인합니다.
```
PS C:\Users\Administrator\Desktop> certutil -store Root
Root "Trusted Root Certification Authorities"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Issuer: CN=MYRootCA
Signature matches Public Key
Root Certificate: Subject matches Issuer
Cert Hash(sha1): cert-hash
No key provider information
Cannot find the certificate and private key for decryption.
CertUtil: -store command completed successfully.
```
1.
**HSM 백엔드 인증서 가져오기**
새 Windows 인스턴스에서 다음을 수행합니다.
1. HSM 백엔드 인증서를 새 Windows 인스턴스에 복사
1. 인증서 가져오기
```
certutil -addstore My signed-certificate-name.cer
```
1.
**HSM 백엔드 인증서 설치 확인**
HSM 백엔드 인증서가 올바르게 설치되었는지 확인합니다.
```
PS C:\Users\Administrator\Desktop> certutil -store My
my "Personal"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US
Non-root Certificate
Cert Hash(sha1): cert-hash
No key provider information
Cannot find the certificate and private key for decryption.
CertUtil: -store command completed successfully.
```
**참고**
후속 단계에서 사용할 인증서 일련 번호를 기록해 둡니다.
1.
**키 참조 파일 생성(선택 사항)**
새로운 키 참조 파일을 생성해야 하는 경우에만 이 단계를 완료합니다. 아니면 다음 단계로 이동합니다.
**참고**
이 기능은 SDK 버전 5.16.0 이상에서만 사용할 수 있습니다.
1. [OpenSSL](https://slproweb.com/products/Win32OpenSSL.html)을 설치하고 모듈러스를 추출합니다.
```
openssl x509 -in signed-certificate-name.cer -modulus -noout
```
**참고**
OpenSSL 명령은 모듈러스를 `Modulus=modulus-value` 형식으로 출력합니다. 다음 명령에 사용할 *modulus-value*을 기록해 둡니다.
1. CloudHSM CLI를 사용하여 키 참조 파일을 생성합니다. [KSP 키 참조 생성(Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference) 섹션을 참조하세요.
```
& "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" key generate-file --encoding ksp-key-reference --filter attr.class=private-key attr.modulus=0xmodulus-value
```
**참고**
CloudHSM CLI 명령 인수의 *modulus-value*에 `0x` 접두사를 붙여 16진수 형식으로 표시해야 합니다.
키 참조 파일은 `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`에서 생성됩니다.
1.
**복구 구성 생성**
다음 콘텐츠가 포함된 `repair.txt`이라는 파일을 생성합니다.
```
[Properties]
11 = "" ; Add friendly name property
2 = "{text}" ; Add Key Provider Information property
_continue_="Container=key-container-name&"
_continue_="Provider=Cavium Key Storage Provider&"
_continue_="Flags=0&"
_continue_="KeySpec=2"
```
**참고**
*key-container-name*을 `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`의 키 참조 파일 이름으로 바꿉니다.
1.
**인증서 저장소 복구**
복구 명령을 실행합니다.
```
certutil -repairstore My certificate-serial-number repair.txt
```
**참고**
인증서 일련 번호는 HSM 백엔드 인증서 설치를 확인할 때 이전 단계에서 가져옵니다.
1.
**인증서 연결 확인**
인증서가 올바르게 연결되었는지 확인합니다.
```
PS C:\Users\Administrator\Desktop> certutil -store My
my "Personal"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US
Non-root Certificate
Cert Hash(sha1): cert-hash
Key Container = key-container-name
Provider = Cavium Key Storage Provider
Private key is NOT exportable
ERROR: Could not verify certificate public key against private key
CertUtil: -store command completed successfully.
```
출력에 다음이 표시되는지 확인합니다.
+ 올바른 키 컨테이너 이름
+ Cavium Key Storage Provider
+ `ERROR: Could not verify certificate public key against private key`는 알려진 문제입니다. [문제: 인증서 저장소 검증 실패](ki-ksp-sdk.md#ki-ksp-1) 섹션을 참조하세요.
1.
**애플리케이션 테스트**
마이그레이션을 완료하기 전에:
1. 개발 환경에서 애플리케이션 테스트
1. 코드를 업데이트하여 주요 변경 사항 해결
1. 애플리케이션별 지침은 [타사 애플리케이션을와 통합 AWS CloudHSM](third-party-applications.md) 섹션 참조
## 마이그레이션 확인
마이그레이션 단계를 완료한 후 다음을 확인합니다.
+ 인증서가 올바른 인증서 저장소에 올바르게 설치되었습니다.
+ 키 참조 파일이 올바른 위치에 있습니다.
+ 애플리케이션이 마이그레이션된 인증서를 사용하여 암호화 작업을 수행할 수 있습니다.
## 문제 해결
마이그레이션 중에 문제가 발생하면 다음을 확인합니다.
+ 소스 시스템에서 모든 인증서를 올바르게 내보냅니다.
+ 시스템 간 인증서 일련 번호가 일치합니다.
+ repair.txt 파일의 키 컨테이너 이름이 키 참조 파일과 일치합니다.
+ SDK3 생성 키 참조 파일을 사용할 경우 SDK3 호환성 모드가 활성화됩니다.
## 관련 주제
+ [의 모범 사례 AWS CloudHSM](best-practices.md)