本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 將您的金鑰儲存提供者 (KSP) 從 AWS CloudHSM 用戶端 SDK 3 遷移至用戶端 SDK 5
<a name="ksp-migrate-to-sdk-5"></a>

本主題說明如何將[金鑰儲存提供者 (KSP)](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，您可以使用 AWS CloudHSM 用戶端軟體開發套件 (SDK) 來執行密碼編譯操作。用戶端 SDK 5 是接收新功能和平台支援更新的主要 SDK。

如需所有供應商的遷移說明，請參閱 [從 AWS CloudHSM 用戶端 SDK 3 遷移至用戶端 SDK 5](client-sdk-migration.md)。

## 遷移至用戶端 SDK 5
<a name="ksp-migrate-steps"></a>

1. 停止用戶端 SDK 3 的用戶端協助程式。

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

1. 在 Windows Server 執行個體上安裝用戶端 SDK 5 金鑰儲存提供者 (KSP)。如需說明，請參閱[安裝 AWS CloudHSM 用戶端 SDK 5 的金鑰儲存提供者 (KSP)](ksp-library-install.md)。

1. 使用新的組態檔案格式和命令列引導工具來設定用戶端 SDK 5 金鑰儲存提供者 (KSP)。如需說明，請參閱[引導用戶端 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)。
**注意**  
搭配用戶端 SDK3 使用用戶端 SDK 3 產生的金鑰參考檔案時，您必須啟用 SDK3 相容性模式。

## 遷移至新的 Windows Server 執行個體
<a name="ksp-migrate-new-windows"></a>

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`包含 的所有內容複製到新 Windows Server 執行個體上的`GlobalPartition`相同目錄路徑。如果目錄不存在，請建立目錄。
   + 如果金鑰參考檔案不存在，請在新的 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}}`。請注意用於下一個命令的{{模數值}}。

   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`表示十六進位格式。  
金鑰參考檔案是在 中建立`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-generated 相容性模式

## 相關主題
<a name="ksp-migrate-to-sdk-5-seealso"></a>
+ [的最佳實務 AWS CloudHSM](best-practices.md)