将您的密钥存储提供程序（KSP）从 AWS CloudHSM Client SDK 3 迁移到 Client SDK 5 - AWS CloudHSM
迁移到 Client SDK 5迁移到新 Windows Server 实例验证迁移故障排除相关主题

将您的密钥存储提供程序（KSP）从 AWS CloudHSM Client SDK 3 迁移到 Client SDK 5

本主题介绍如何将密钥存储提供程序（KSP） 从 AWS CloudHSM Client SDK 3 迁移到 Client SDK 5。AWS CloudHSM Client SDK 的最新版本是 5.16。有关迁移优势的信息，请参阅 AWS CloudHSM Client SDK 5 的优点。

在 AWS CloudHSM 中，使用 AWS CloudHSM Client 软件开发工具包（SDK）执行加密操作。Client SDK 5 是接收新功能和平台支持更新的主要 SDK。

有关所有提供程序的迁移说明，请参阅 从 AWS CloudHSM Client SDK 3 迁移到 Client SDK 5。

迁移到 Client SDK 5

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

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

  2. 在 Windows Server 实例上安装 Client SDK 5 密钥存储提供程序（KSP）。有关说明，请参阅为 AWS CloudHSM Client SDK 5 安装密钥存储提供程序（KSP）。

  3. 使用新的配置文件格式和命令行引导工具配置 Client SDK 5 密钥存储提供程序（KSP）。有关说明，请参阅引导客户端软件开发工具包。

  4. AWS CloudHSM Client SDK 5 的密钥存储提供程序（KSP）包括 SDK3 兼容模式，进而支持 SDK3 中生成的密钥引用文件。有关更多信息，请参阅 AWS CloudHSM 的密钥存储提供程序（KSP）的 SDK3 兼容模式。

    注意

    在 Client SDK 5 中使用 Client SDK 3 生成的密钥引用文件时，必须启用 SDK3 兼容模式。

迁移到新 Windows Server 实例

  1. 在新 Windows Server 实例上完成迁移到 Client SDK 5 中的所有步骤。

  2. 检查现有的密钥引用文件

    在您的原始 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）。

  3. 验证根证书

    在受信任的根证书颁发机构中检查根证书：

    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.
    注意

    记下证书序列号，以便在下一步中使用。

  4. 导出根证书

    将根证书导出到文件中：

    certutil -store Root certificate-serial-number root-certificate-name.cer
  5. 验证 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.
    注意

    记下证书序列号，以便在下一步中使用。

  6. 导出 HSM 后端证书

    将 HSM 后端证书导出到文件中：

    certutil -store My certificate-serial-number signed-certificate-name.cer
  7. 导入根证书

    在新 Windows 实例上：

    1. 将根 CA 文件复制到新 Windows 实例

    2. 导入证书：

      certutil -addstore Root root-certificate-name.cer
  8. 验证根证书的安装

    确认根证书已正确安装：

    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.
  9. 导入 HSM 后端证书

    在新 Windows 实例上：

    1. 将 HSM 后端证书复制到新 Windows 实例

    2. 导入证书：

      certutil -addstore My signed-certificate-name.cer
  10. 验证 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.
    注意

    记下证书序列号，以便在后续步骤中使用。

  11. 创建密钥引用文件（可选）

    仅在需要创建新的密钥引用文件时，完成此步骤。否则，转到下一步。

    注意

    此功能只在 SDK 版本 5.16.0 及更高版本中提供。

    1. 安装 OpenSSL 并提取模数：

      openssl x509 -in signed-certificate-name.cer -modulus -noout
      注意

      OpenSSL 命令以以下格式输出模数：Modulus=modulus-value。记下 modulus-value，以便在下一个命令中使用。

    2. 使用 CloudHSM CLI 创建密钥引用文件，请参阅 生成 KSP 密钥引用（Windows）：

      & "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 表示十六进制格式。

      密钥引用文件是在 C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition 中创建的。

  12. 创建修复配置

    使用以下内容创建名为 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 中的密钥引用文件名。

  13. 修复证书存储

    运行修复命令：

    certutil -repairstore My certificate-serial-number repair.txt
    注意

    证书序列号是在验证 HSM 后端证书安装时的先前步骤中获取的。

  14. 验证证书关联

    确认证书已正确关联：

    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 是一个已知问题，请参阅 问题：验证证书存储失败

  15. 测试您的应用程序

    在完成迁移之前：

    1. 在您的开发环境中测试应用程序

    2. 更新代码以解决任何重大更改

    3. 有关特定于应用程序的指导，请参阅 将第三方应用程序与 AWS CloudHSM 集成

验证迁移

完成迁移步骤后，请验证：

  • 证书已正确安装在正确的证书存储中

  • 密钥引用文件位于正确的位置

  • 应用程序可以使用迁移的证书执行加密操作

故障排除

如果在迁移过程中遇到问题，请验证：

  • 所有证书均已从源系统正确导出

  • 系统之间的证书序列号匹配

  • repair.txt 文件中的密钥容器名称与密钥引用文件相匹配

  • 如果使用 SDK3 生成的密钥引用文件，则启用 SDK3 兼容模式

相关主题