翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 への移行
では AWS CloudHSM、顧客アプリケーションは AWS CloudHSM クライアントソフトウェア開発キット (SDK) を使用して暗号化オペレーションを実行します。クライアント SDK 5 は、新しい機能とプラットフォームサポートが継続的に追加される、主要な SDK です。
クライアント SDK 3 には、ユーザー管理用の CMU と、キー管理およびキー操作用の KMU という 2 つの独立したコマンドラインツールが含まれています。クライアント SDK 5 は、CMU と KMU (クライアント SDK 3 で提供されていたツール) の機能を 1 つのツール [AWS CloudHSM コマンドラインインターフェイス (CLI)](cloudhsm_cli.md) に統合します。ユーザー管理オペレーションは、 サブコマンド [CloudHSM CLI のユーザーカテゴリ](cloudhsm_cli-user.md) と [CloudHSM CLI のクォーラムカテゴリ](cloudhsm_cli-qm.md) で実行できます。キー管理オペレーションは [key サブコマンド](cloudhsm_cli-key.md)、暗号化オペレーションは [crypto サブコマンド](cloudhsm_cli-crypto.md)の下にあります。コマンドの完全なリストについては、「[CloudHSM CLI コマンドのリファレンス](cloudhsm_cli-reference.md)」を参照してください。
移行の利点については、「[AWS CloudHSM クライアント SDK 5 の利点](client-sdk-5-benefits.md)」を参照してください。
クライアント SDK 3 からクライアント SDK 5 への移行手順については、以下のトピックを参照してください。 AWS CloudHSM Client SDK の最新バージョンは 5.16 です。
+ [AWS CloudHSM PKCS \$111 ライブラリをクライアント SDK 3 からクライアント SDK 5 に移行する](pkcs11-migrate-to-sdk-5.md)
+ [OpenSSL 動的エンジンを AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する](openssl-migrate-to-sdk-5.md)
+ [キーストレージプロバイダー (KSP) を AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する](ksp-migrate-to-sdk-5.md)
+ [JCE プロバイダーを AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する](java-lib-migrate_to_sdk5.md)
CloudHSM CLI でサポートされていない機能やユースケースについては、[AWS サポート](https://support.console.aws.amazon.com/support/home#/) にお問い合わせください。
# AWS CloudHSM PKCS \$111 ライブラリをクライアント SDK 3 からクライアント SDK 5 に移行する
このトピックを使用して、 AWS CloudHSM [PKCS \$111 ライブラリ](pkcs11-library.md)をクライアント SDK 3 からクライアント SDK 5 に移行します。移行の利点については、「[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 3 メカニズム | 同等のクライアント SDK 5 メカニズム |
| --- | --- |
| `CKM_AES_KEY_WRAP` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` |
| `CKM_AES_KEY_WRAP_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` |
| `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` |
| `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` |
| `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` |
### ECDH
クライアント SDK 3 では、ECDH を使用して KDF を指定できます。この機能は、現在クライアント SDK 5 では利用できません。アプリケーションにこの機能が必要な場合は、[サポート](https://support.console.aws.amazon.com/support/home#/)にお問い合わせください。
### キーハンドルがセッション固有になりました
クライアント SDK 5 でキーハンドルを正常に使用する場合、アプリケーションを実行するたびにキーハンドルを取得する必要があります。異なるセッション間で同じキーハンドルを使用することが予想される既存のアプリケーションがある場合、アプリケーションを実行するたびにキーハンドルを取得するようにコードを変更することが必要です。キーハンドルの取得については、[この AWS CloudHSM PKCS \$111 の例](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/find_objects/find_objects.c)を参照してください。この変更は、[PKCS \$111 2.40 仕様](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc416959689) に準拠したものです。
## クライアント SDK 5 への移行
このセクションの指示に従って、クライアント SDK 3 から クライアント SDK 5 に移行します。
**注記**
Amazon Linux、Ubuntu 16.04、Ubuntu 18.04、CentOS 6、CentOS 8、および RHEL 6 は現在、クライアント SDK 5 ではサポートされていません。現在、クライアント SDK 3 でこれらのプラットフォームのいずれかを使用している場合は、クライアント SDK 5 に移行するときに別のプラットフォームを選択する必要があります。
1. クライアント SDK 3 用の PKCS \$111 ライブラリのアンインストールします。
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client-pkcs11
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client-pkcs11
```
------
1. クライアント SDK 3 の Client Daemon を停止します。
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
1. クライアント SDK 3 の Client Daemon をアンインストールします。
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
**注記**
カスタム設定を再度有効にする必要があります。
1. 「[AWS CloudHSM クライアント SDK 5 用の PKCS \$111 ライブラリをインストールする](pkcs11-library-install.md)」の手順に従って、クライアント SDK PKCS \$111 ライブラリをインストールします。
1. クライアント SDK 5 では、新しい設定ファイル形式とコマンドラインブートストラップツールが導入されました。クライアント SDK 5 PKCS \$111 ライブラリをブートストラップするには、[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to) のユーザーガイドに記載されている手順に従ってください。
1. アプリケーションは開発環境で実行されていること。既存のコードを更新して、最終的な移行前に重大な変更を解決します。
## 関連トピック
+ [のベストプラクティス AWS CloudHSM](best-practices.md)
# OpenSSL 動的エンジンを AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する
このトピックを使用して、[OpenSSL Dynamic Engine](openssl-library.md) を AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行します。移行の利点については、「[AWS CloudHSM クライアント SDK 5 の利点](client-sdk-5-benefits.md)」を参照してください。
では AWS CloudHSM、顧客アプリケーションは AWS CloudHSM クライアントソフトウェア開発キット (SDK) を使用して暗号化オペレーションを実行します。クライアント SDK 5 は、新しい機能とプラットフォームサポートが継続的に追加される、主要な SDK です。
**注記**
乱数生成は現在、OpenSSL Dynamic Engine を使用するクライアント SDK 5 ではサポートされていません。
すべてのプロバイダーの移行手順を確認するには、「」を参照してください[AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 への移行](client-sdk-migration.md)。
## クライアント SDK 5 への移行
このセクションの指示に従って、クライアント SDK 3 から クライアント SDK 5 に移行します。
**注記**
Amazon Linux、Ubuntu 16.04、Ubuntu 18.04、CentOS 6、CentOS 8、および RHEL 6 は現在、クライアント SDK 5 ではサポートされていません。現在、クライアント SDK 3 でこれらのプラットフォームのいずれかを使用している場合は、クライアント SDK 5 に移行するときに別のプラットフォームを選択する必要があります。
1. クライアント SDK 3 用の OpenSSL Dynamic Engine をアンインストールする
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client-dyn
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client-dyn
```
------
1. クライアント SDK 3 の Client Daemon を停止します。
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
1. クライアント SDK 3 の Client Daemon をアンインストールします。
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
**注記**
カスタム設定を再度有効にする必要があります。
1. 「[AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine をインストールする](openssl5-install.md)」の手順に従って、クライアント SDK OpenSSL Dynamic Engine をインストールします。
1. クライアント SDK 5 では、新しい設定ファイル形式とコマンドラインブートストラップツールが導入されました。クライアント SDK 5 OpenSSL Dynamic Engine をブートストラップするには、ユーザー ガイドの [クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to) に記載されている手順に従ってください。
1. アプリケーションは開発環境で実行されていること。既存のコードを更新して、最終的な移行前に重大な変更を解決します。
## 関連トピック
+ [のベストプラクティス AWS CloudHSM](best-practices.md)
# キーストレージプロバイダー (KSP) を AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する
このトピックでは、 AWS CloudHSM クライアント SDK 3 から クライアント SDK 5 へ[キーストレージプロバイダー (KSP)](ksp-library.md) を移行する方法について説明します。 AWS CloudHSM Client 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 への移行
1. クライアント SDK 3 の Client Daemon を停止します。
```
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)」を参照してください。
**注記**
クライアント SDK 5 でクライアント SDK 3 によって生成されたキー参照ファイルを使用する場合、SDK3 互換モードを有効にする必要があります。
## 新しい Windows Server インスタンスへの移行
1. 新しい Windows Server インスタンス上で、[クライアント 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) をインストールし、modulus を抽出します。
```
openssl x509 -in signed-certificate-name.cer -modulus -noout
```
**注記**
OpenSSL コマンドは、modulus を次の形式で出力します: `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* には、16 進数形式を示すために先頭に `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) を参照してください。
## 移行を確認する
移行手順を完了したら、以下を確認します。
+ 証明書が正しい証明書ストアに正しくインストールされている
+ キー参照ファイルが正しい場所にある
+ 移行された証明書を使用してアプリケーションが暗号化オペレーションを実行できる
## トラブルシューティング
移行中に問題が発生した場合は、以下を確認します。
+ すべての証明書がソースシステムから適切にエクスポートされている
+ 証明書のシリアル番号がシステム間で一致している
+ repair.txt ファイル内のキーコンテナ名がキー参照ファイルと一致している
+ SDK3 で生成されたキー参照ファイルを使用している場合は、SDK3 互換モードが有効になっている
## 関連トピック
+ [のベストプラクティス AWS CloudHSM](best-practices.md)
# JCE プロバイダーを AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する
このトピックを使用して、[JCE プロバイダー](java-library.md)を AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行します。移行の利点については、「[AWS CloudHSM クライアント SDK 5 の利点](client-sdk-5-benefits.md)」を参照してください。
では AWS CloudHSM、顧客アプリケーションは AWS CloudHSM クライアントソフトウェア開発キット (SDK) を使用して暗号化オペレーションを実行します。クライアント SDK 5 は、新しい機能とプラットフォームサポートが継続的に追加される、主要な SDK です。
クライアント SDK 3 JCE プロバイダーは、標準 JCE 仕様に含まれていないカスタムクラスと API を使用します。JCE プロバイダーのクライアント SDK 5 は JCE 仕様に準拠しており、特定の領域ではクライアント SDK 3 と下位互換性がありません。お客様のアプリケーションでは、クライアント SDK 5 への移行の一環として変更が必要になる場合があります。このセクションでは、移行を成功させるために必要な変更点を概説します。
すべてのプロバイダーの移行手順を確認するには、「」を参照してください[AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 への移行](client-sdk-migration.md)。
**Topics**
+ [重大な変更に対処して準備する](#jce-migration-preparation-sdk5)
+ [クライアント SDK 5 への移行](#w2aac25c19c21c15)
+ [関連トピック](#java-lib-migrate_to_sdk5-seealso)
## 重大な変更に対処して準備する
これらの重大な変更を確認し、それに応じて開発環境でアプリケーションを更新します。
### プロバイダークラスと名前が変更されました
****
| 変更点 | クライアント SDK 3 の内容 | クライアント SDK 5 の内容 | 例 |
| --- | --- | --- | --- |
| プロバイダークラスと名前 | クライアント SDK 3 の JCE プロバイダークラスは `CaviumProvider` と呼ばれ、プロバイダー名は `Cavium` です。 | クライアント SDK 5 では、プロバイダー クラスは `CloudHsmProvider` と呼ばれ、プロバイダー名 `CloudHSM` があります。 | `CloudHsmProvider` オブジェクトを初期化する方法は、[AWS CloudHSM GitHub サンプルリポジトリ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java#L43-L50)を参照してください。 |
### 明示的なログインが変更されましたが、暗黙的なログインは従来通りです。
****
| 変更点 | クライアント SDK 3 の内容 | クライアント SDK 5 の内容 | 例 |
| --- | --- | --- | --- |
| 明示的なログイン | クライアント SDK 3 は、明示的なログイン [1](#explicit_login_sdk3_note) に `LoginManager` クラスを使用します。 | クライアント SDK 5 では、`CloudHSM` プロバイダーは明示的なログインのために `AuthProvider` を実装します。 `AuthProvider` は標準の Java クラスであり、Java の慣用的な方法でプロバイダーにログインします。クライアント SDK 5 でログイン状態管理が改善されたため、アプリケーションは再接続中にログインをモニタリングして実行する必要がなくなりました[2](#explicit_login_sdk5_note)。 | クライアント SDK 5 で明示的なログインを使用する方法の例については、[AWS CloudHSM GitHub サンプルリポジトリの LoginRunner サンプル](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141)を参考にしてください。 |
| 暗黙的なログイン | 暗黙的なログインには変更は必要ありません。クライアント SDK 3 からクライアント SDK 5 に移行する場合、暗黙的なログインでも同じプロパティファイルとすべての環境変数が引き続き機能します。 | クライアント SDK 5 で暗黙的なログインを使用する方法の例については、 AWS CloudHSM GitHub サンプルリポジトリの [LoginRunner ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L143-L202) サンプルを参照してください。 |
+ [1] クライアント SDK 3 コードスニペット:
```
LoginManager lm = LoginManager.getInstance();
lm.login(partition, user, pass);
```
+ [2] クライアント SDK 5 コードスニペット:
```
// Construct or get the existing provider object
AuthProvider provider = new CloudHsmProvider();
// Call login method on the CloudHsmProvider object
// Here loginHandler is a CallbackHandler
provider.login(null, loginHandler);
```
クライアント SDK 5 で明示的なログインを使用する方法の例については、 AWS CloudHSM GitHub サンプルリポジトリの [LoginRunner ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141) サンプルを参照してください。
### キー生成が変更されました
****
| 変更点 | クライアント SDK 3 の内容 | クライアント SDK 5 の内容 | 例 |
| --- | --- | --- | --- |
| キー生成 | クライアント SDK 3 では、 `Cavium[Key-type]AlgorithmParameterSpec` はキー生成パラメータの指定に使用されます。コードスニペットについては、脚注 [1](#key_generation_sdk3_note) を参照してください。 | Client SDK 5 では、キー生成属性の指定に `KeyAttributesMap` が使用されます。コードスニペットについては、脚注 [2](#key_generation_sdk5_note) を参照してください。 | `KeyAttributesMap` を使用して対称キーを生成する方法の例については、AWS CloudHSM Github サンプルリポジトリの [SymmetricKeys サンプル](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)を参考にしてください。 |
| キーペアの生成 | クライアント SDK 3 では、 `Cavium[Key-type]AlgorithmparameterSpec` を使用してキーペア生成パラメータを指定します。コードスニペットについては、脚注 [3](#key_pair_generation_sdk3_note) を参照してください。 | Client SDK 5 では、これらのパラメーターの指定に `KeyPairAttributesMap` が使用されます。コードスニペットについては、脚注 [4](#key_pair_generation_sdk5_note) を参照してください。 | `KeyAttributesMap` を使用して非対称キーを生成する方法の例については、 AWS CloudHSM GitHub [サンプルリポジトリの AsymmetricKeys ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java) サンプルを参照してください。 |
+ [1] クライアント SDK 3 キー生成のコードスニペット:
```
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec aesSpec = new CaviumAESKeyGenParameterSpec(
keySizeInBits,
keyLabel,
isExtractable,
isPersistent);
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();
```
+ [2] クライアント SDK 5 キー生成のコードスニペット:
```
KeyGenerator keyGen = KeyGenerator.getInstance("AES",
CloudHsmProvider.PROVIDER_NAME);
final KeyAttributesMap aesSpec = new KeyAttributesMap();
aesSpec.put(KeyAttribute.LABEL, keyLabel);
aesSpec.put(KeyAttribute.SIZE, keySizeInBits);
aesSpec.put(KeyAttribute.EXTRACTABLE, isExtractable);
aesSpec.put(KeyAttribute.TOKEN, isPersistent);
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();
```
+ [3] クライアント SDK 3 キーペア生成のコードスニペット:
```
KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("rsa", "Cavium");
CaviumRSAKeyGenParameterSpec spec = new CaviumRSAKeyGenParameterSpec(
keySizeInBits,
new BigInteger("65537"),
label + ":public",
label + ":private",
isExtractable,
isPersistent);
keyPairGen.initialize(spec);
keyPairGen.generateKeyPair();
```
+ [4] クライアント SDK 5 キーペア生成のコードスニペット:
```
KeyPairGenerator keyPairGen =
KeyPairGenerator.getInstance("RSA", providerName);
// Set attributes for RSA public key
final KeyAttributesMap publicKeyAttrsMap = new KeyAttributesMap();
publicKeyAttrsMap.putAll(additionalPublicKeyAttributes);
publicKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Public");
publicKeyAttrsMap.put(KeyAttribute.MODULUS_BITS, keySizeInBits);
publicKeyAttrsMap.put(KeyAttribute.PUBLIC_EXPONENT,
new BigInteger("65537").toByteArray());
// Set attributes for RSA private key
final KeyAttributesMap privateKeyAttrsMap = new KeyAttributesMap();
privateKeyAttrsMap.putAll(additionalPrivateKeyAttributes);
privateKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Private");
// Create KeyPairAttributesMap and use that to initialize the
// keyPair generator
KeyPairAttributesMap keyPairSpec =
new KeyPairAttributesMapBuilder()
.withPublic(publicKeyAttrsMap)
.withPrivate(privateKeyAttrsMap)
.build();
keyPairGen.initialize(keyPairSpec);
keyPairGen.generateKeyPair();
```
### キーの検索、削除、参照が変更されました
で既に生成されたキーを検索するには、KeyStore AWS CloudHSM を使用します。クライアント SDK 3 には、 `Cavium` と `CloudHSM` の 2 つの KeyStore タイプがあります。クライアント SDK 5 には KeyStore タイプが 1 つだけあります: `CloudHSM`。
`Cavium` KeyStore から `CloudHSM` KeyStore に移動するには、キーストアタイプを変更する必要があります。さらに、クライアント SDK 3 ではキーハンドルでキーを参照していたのに対し、クライアント SDK 5 ではキーラベルを使用するようになりました。これにより、以下の動作が変更されています。
| 変更点 | クライアント SDK 3 の内容 | クライアント SDK 5 の内容 | 例 |
| --- | --- | --- | --- |
| キーリファレンス | クライアント SDK 3 では、アプリケーションはキーラベルまたはキーハンドルを使用して HSM 内のキーを参照します。KeyStore でラベルを使用してキーを検索するか、ハンドルを使用して `CaviumKey` オブジェクトを作成します。 | クライアント SDK 5 では、アプリケーションは [クライアント SDK 5 のAWS CloudHSM KeyStore Java クラス](alternative-keystore_5.md) を使用してラベルでキーを検索できます。ハンドルでキーを検索するには、 で AWS CloudHSM `KeyStoreWithAttributes`を使用します AWS CloudHSM `KeyReferenceSpec`。 | |
| 複数のエントリの検索 | 同じ基準を持つ複数の項目が `Cavium` KeyStore に存在するシナリオで `getEntry`、`getKey`、または `getCertificate` を使用してキーを検索すると、最初に見つかったエントリのみが返されます。 | および AWS CloudHSM `KeyStore`の場合`KeyStoreWithAttributes`、この同じシナリオでは例外がスローされます。この問題を解決するには、CloudHSM CLI で [CloudHSM CLI でキーの属性を設定する](cloudhsm_cli-key-set-attribute.md) コマンドを使用してキーに一意のラベルを設定することをお勧めします。または、`KeyStoreWithAttributes#getKeys` を使用して、基準に一致するすべてのキーを返します。 | |
| すべてのキーを検索する | クライアント SDK 3 では、 を使用して HSM 内のすべてのキーを検索できます`Util.findAllKeys()`。 | クライアント SDK 5 では、 `KeyStoreWithAttributes` クラスを使用することで、キーの検索がより簡単かつ効率的になります。可能であれば、レイテンシーを最小限に抑えるためにキーをキャッシュします。詳細については、「[アプリケーションのキーを効果的に管理する](bp-application-integration.md#bp-manage-application)」を参照してください。HSM からすべてのキーを取得する必要がある場合は、空の `KeyAttributesMap` を指定して `KeyStoreWithAttributes#getKeys` を使用します。 | `KeyStoreWithAttributes` クラスを使用してキーを検索する例は、[AWS CloudHSM Github サンプルリポジトリ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L205-L223)で入手できます。コードスニペットは [1](#using_keystore_att_note) に示されています。 |
| キー削除 | クライアント SDK 3 は `Util.deleteKey()` を使用してキーを削除します。 | クライアント SDK 5 の `Key` オブジェクトは、この`Destroyable`インターフェイスの `destroy()`メソッドを使用してキーを削除できるインターフェイスを実装します。 | キーの削除機能を示すサンプル コードは、[CloudHSM Github サンプルリポジトリ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L229-L234)にあります。各 SDK のサンプルスニペットを [2](#delete_key_note) に示します。 |
+ [1] スニペットを次に示します。
```
KeyAttributesMap findSpec = new KeyAttributesMap();
findSpec.put(KeyAttribute.LABEL, label);
findSpec.put(KeyAttribute.KEY_TYPE, keyType);
KeyStoreWithAttributes keyStore = KeyStoreWithAttributes.getInstance("CloudHSM");
keyStore.load(null, null);
keyStore.getKey(findSpec);
```
+ [2] クライアント SDK 3 でキーを削除する:
```
Util.deleteKey(key);
```
クライアント SDK 5 でキーを削除する:
```
((Destroyable) key).destroy();
```
### 暗号アンラップオペレーションが変更されましたが、他の暗号オペレーションは変更されていません
**注記**
Cipher の暗号化/復号化/ラップオペレーションに変更は必要ありません。
アンラップオペレーションでは、クライアント SDK 3 `CaviumUnwrapParameterSpec` クラスを、リストされている暗号化オペレーションに固有の次のクラスのいずれかに置き換える必要があります。
+ `AES/GCM/NoPadding` ラップ解除のための `GCMUnwrapKeySpec`
+ `AESWrap unwrap` と `AES/CBC/NoPadding unwrap` の場合は `IvUnwrapKeySpec`
+ `RSA OAEP unwrap` 用の `OAEPUnwrapKeySpec`
`OAEPUnwrapkeySpec` のスニペットの例
```
OAEPParameterSpec oaepParameterSpec =
new OAEPParameterSpec(
"SHA-256",
"MGF1",
MGF1ParameterSpec.SHA256,
PSpecified.DEFAULT);
KeyAttributesMap keyAttributesMap =
new KeyAttributesMap(KeyAttributePermissiveProfile.KEY_CREATION);
keyAttributesMap.put(KeyAttribute.TOKEN, true);
keyAttributesMap.put(KeyAttribute.EXTRACTABLE, false);
OAEPUnwrapKeySpec spec = new OAEPUnwrapKeySpec(oaepParameterSpec,
keyAttributesMap);
Cipher hsmCipher =
Cipher.getInstance(
"RSA/ECB/OAEPPadding",
CloudHsmProvider.PROVIDER_NAME);
hsmCipher.init(Cipher.UNWRAP_MODE, key, spec);
```
### 署名オペレーションは変更されていません
署名オペレーションに変更は必要ありません。
## クライアント SDK 5 への移行
このセクションの指示に従って、クライアント SDK 3 から クライアント SDK 5 に移行します。
**注記**
Amazon Linux、Ubuntu 16.04、Ubuntu 18.04 CentOS 6、CentOS 8、および RHEL 6 は現在、クライアント SDK 5 ではサポートされていません。現在、クライアント SDK 3 でこれらのプラットフォームのいずれかを使用している場合は、クライアント SDK 5 に移行するときに別のプラットフォームを選択する必要があります。
1. クライアント SDK 3 向けの JCE プロバイダーをアンインストールします。
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client-jce
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client-jce
```
------
1. クライアント SDK 3 の Client Daemon を停止します。
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
1. クライアント SDK 3 の Client Daemon をアンインストールします。
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
**注記**
カスタム設定を再度有効にする必要があります。
1. 「[AWS CloudHSM クライアント SDK 5 の JCE プロバイダーをインストールする](java-library-install_5.md)」の手順に従って、クライアント SDK JCE プロバイダーをインストールします。
1. クライアント SDK 5 では、新しい設定ファイル形式とコマンドラインブートストラップツールが導入されました。クライアント SDK 5 JCE プロバイダーをブートストラップするには、ユーザー ガイドの 「[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to)」に記載されている手順に従ってください。
1. アプリケーションは開発環境で実行されていること。既存のコードを更新して、最終的な移行前に重大な変更を解決します。
## 関連トピック
+ [のベストプラクティス AWS CloudHSM](best-practices.md)