本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 将您的密钥存储提供程序 (KSP) 从 AWS CloudHSM 客户端 SDK 3 迁移到客户端 SDK 5
<a name="ksp-migrate-to-sdk-5"></a>

本主题介绍如何将[密钥存储提供程序（KSP）](ksp-library.md) 从 AWS CloudHSM Client SDK 3 迁移到 Client SDK 5。 AWS CloudHSM 客户端 SDK 的最新版本是 5.16。有关迁移优势的信息，请参阅 [AWS CloudHSM 客户端 SDK 的好处 5](client-sdk-5-benefits.md)。

在中 AWS CloudHSM，您可以使用 AWS CloudHSM 客户端软件开发套件 (SDK) 执行加密操作。Client SDK 5 是接收新功能和平台支持更新的主要 SDK。

有关所有提供程序的迁移说明，请参阅 [从 AWS CloudHSM 客户端 SDK 3 迁移到客户端 SDK 5](client-sdk-migration.md)。

## 迁移到 Client SDK 5
<a name="ksp-migrate-steps"></a>

1. 停止 Client SDK 3 的客户端进程守护程序。

   ```
   PS C:\> Stop-Service "AWS CloudHSM Client"
   ```

1. 在 Windows Server 实例上安装 Client SDK 5 密钥存储提供程序（KSP）。有关说明，请参阅[为 AWS CloudHSM 客户端 SDK 5 安装密钥存储提供程序 (KSP)](ksp-library-install.md)。

1. 使用新的配置文件格式和命令行引导工具配置 Client SDK 5 密钥存储提供程序（KSP）。有关说明，请参阅[引导客户端软件开发工具包](cluster-connect.md#connect-how-to)。

1.  AWS CloudHSM 客户端 SDK 5 的密钥存储提供程序 (KSP) 包括 SDK3 兼容模式，以支持在中 SDK3生成的密钥参考文件。有关更多信息，请参阅 [SDK3 密钥存储提供程序 (KSP) 的兼容模式 AWS CloudHSM](ksp-library-configs-sdk3-compatibility-mode.md)。
**注意**  
在客户端 SDK 5 中使用客户端 SDK 3 生成的密钥参考文件时，必须启用 SDK3 兼容模式。

## 迁移到新 Windows Server 实例
<a name="ksp-migrate-new-windows"></a>

1. 在新 Windows Server 实例上完成[迁移到 Client SDK 5](#ksp-migrate-steps) 中的所有步骤。

1. 

**检查现有的密钥引用文件**  
在您的原始 Windows Server 实例上，在 `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition` 中查看密钥引用文件。
   + 如果存在密钥引用文件，请将包括 `GlobalPartition` 的 `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP` 下的所有内容复制到新 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=0x{{modulus-value}}
      ```
**注意**  
CloudHSM CLI 命令参数必须以`0x`前缀表示十六{{modulus-value}}进制格式。  
密钥引用文件是在 `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 密钥存储提供程序
   + `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)

## 验证迁移
<a name="ksp-migrate-verification"></a>

完成迁移步骤后，请验证：
+ 证书已正确安装在正确的证书存储中
+ 密钥引用文件位于正确的位置
+ 应用程序可以使用迁移的证书执行加密操作

## 问题排查
<a name="ksp-migrate-troubleshooting"></a>

如果在迁移过程中遇到问题，请验证：
+ 所有证书均已从源系统正确导出
+ 系统之间的证书序列号匹配
+ repair.txt 文件中的密钥容器名称与密钥引用文件相匹配
+ SDK3 如果使用 SDK3生成的密钥引用文件，则启用兼容模式

## 相关主题
<a name="ksp-migrate-to-sdk-5-seealso"></a>
+ [的最佳实践 AWS CloudHSM](best-practices.md)