翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 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)