AWS CloudHSM クライアント SDK 3 から クライアント SDK 5 へキーストレージプロバイダー (KSP) を移行する - AWS CloudHSM
クライアント SDK 5 への移行新しい Windows Server インスタンスへの移行移行を確認するトラブルシューティング関連トピック

AWS CloudHSM クライアント SDK 3 から クライアント SDK 5 へキーストレージプロバイダー (KSP) を移行する

このトピックでは、AWS CloudHSM クライアント SDK 3 から クライアント SDK 5 へキーストレージプロバイダー (KSP) を移行する方法について説明します。AWS CloudHSM Client SDK の最新バージョンは 5.16 です。移行のメリットに関する詳細については、AWS CloudHSM クライアント SDK 5 の利点 を参照してください。

AWS CloudHSM では、AWS CloudHSM クライアント Software Development Kit (SDK) を使用して暗号化オペレーションを実行します。クライアント SDK 5 は、新機能やプラットフォームサポートの更新を受け取る主要な SDK です。

すべてのプロバイダーの移行手順については、AWS CloudHSM クライアント SDK 3 から クライアント SDK 5 への移行 を参照してください。

クライアント SDK 5 への移行

  1. クライアント SDK 3 の Client Daemon を停止します。

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

  2. Windows Server インスタンスにクライアント SDK 5 キーストレージプロバイダー (KSP) をインストールします。手順については、「AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) をインストールする」を参照してください。

  3. 新しい設定ファイル形式およびコマンドラインのブートストラップツールを使用して、クライアント SDK 5 キーストレージプロバイダー (KSP) を設定します。手順については、「クライアント SDK をブートストラップする」を参照してください。

  4. AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) には、SDK3 で生成されたキー参照ファイルをサポートするための SDK3 互換モードが含まれています。詳細については、「AWS CloudHSM 用キーストレージプロバイダー (KSP) の SDK3 互換モード」を参照してください。

    注記

    クライアント SDK 5 でクライアント SDK 3 によって生成されたキー参照ファイルを使用する場合、SDK3 互換モードを有効にする必要があります。

新しい Windows Server インスタンスへの移行

  1. 新しい Windows Server インスタンス上で、クライアント 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 をインストールし、modulus を抽出します。

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

      OpenSSL コマンドは、modulus を次の形式で出力します: 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 には、16 進数形式を示すために先頭に 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 互換モードが有効になっている

関連トピック