JCE プロバイダーを AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する - AWS CloudHSM

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

JCE プロバイダーを AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行する

このトピックを使用して、JCE プロバイダーを AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 に移行します。移行の利点については、「AWS CloudHSM クライアント SDK 5 の利点」を参照してください。

では 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 への移行

重大な変更に対処して準備する

これらの重大な変更を確認し、それに応じて開発環境でアプリケーションを更新します。

プロバイダークラスと名前が変更されました

変更点 クライアント SDK 3 の内容 クライアント SDK 5 の内容

プロバイダークラスと名前

クライアント SDK 3 の JCE プロバイダークラスは CaviumProvider と呼ばれ、プロバイダー名は Cavium です。

クライアント SDK 5 では、プロバイダー クラスは CloudHsmProvider と呼ばれ、プロバイダー名 CloudHSM があります。

CloudHsmProvider オブジェクトを初期化する方法は、AWS CloudHSM GitHub サンプルリポジトリを参照してください。

明示的なログインが変更されましたが、暗黙的なログインは従来通りです。

変更点 クライアント SDK 3 の内容 クライアント SDK 5 の内容

明示的なログイン

クライアント SDK 3 は、明示的なログイン 1LoginManager クラスを使用します。

クライアント SDK 5 では、CloudHSM プロバイダーは明示的なログインのために AuthProvider を実装します。 AuthProvider は標準の Java クラスであり、Java の慣用的な方法でプロバイダーにログインします。クライアント SDK 5 でログイン状態管理が改善されたため、アプリケーションは再接続中にログインをモニタリングして実行する必要がなくなりました2

クライアント SDK 5 で明示的なログインを使用する方法の例については、AWS CloudHSM GitHub サンプルリポジトリの LoginRunner サンプルを参考にしてください。

暗黙的なログイン

暗黙的なログインには変更は必要ありません。クライアント SDK 3 からクライアント SDK 5 に移行する場合、暗黙的なログインでも同じプロパティファイルとすべての環境変数が引き続き機能します。

クライアント SDK 5 で暗黙的なログインを使用する方法の例については、 AWS CloudHSM GitHub サンプルリポジトリの LoginRunner サンプルを参照してください。

  • [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 サンプルを参照してください。

キー生成が変更されました

変更点 クライアント SDK 3 の内容 クライアント SDK 5 の内容

キー生成

クライアント SDK 3 では、 Cavium[Key-type]AlgorithmParameterSpec はキー生成パラメータの指定に使用されます。コードスニペットについては、脚注 1 を参照してください。

Client SDK 5 では、キー生成属性の指定に KeyAttributesMap が使用されます。コードスニペットについては、脚注 2 を参照してください。

KeyAttributesMap を使用して対称キーを生成する方法の例については、AWS CloudHSM GitHub サンプルリポジトリの SymmetricKeys サンプルを参照してください。

キーペアの生成

クライアント SDK 3 では、 Cavium[Key-type]AlgorithmparameterSpec を使用してキーペア生成パラメータを指定します。コードスニペットについては、脚注 3 を参照してください。

Client SDK 5 では、これらのパラメーターの指定に KeyPairAttributesMap が使用されます。コードスニペットについては、脚注 4 を参照してください。

KeyAttributesMap を使用して非対称キーを生成する方法の例については、 AWS CloudHSM GitHub サンプルリポジトリの AsymmetricKeys サンプルを参照してください。

  • [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 には、 CaviumCloudHSM の 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 クラス を使用してラベルでキーを検索できます。ハンドルでキーを検索するには、 で AWS CloudHSM KeyStoreWithAttributesを使用します AWS CloudHSM KeyReferenceSpec

複数のエントリの検索

Cavium KeyStore に同じ条件を持つ複数の項目が存在するシナリオgetCertificategetEntry、、getKey、または を使用してキーを検索すると、見つかった最初のエントリのみが返されます。

と AWS CloudHSM KeyStoreではKeyStoreWithAttributes、この同じシナリオにより例外がスローされます。この問題を解決するには、CloudHSM CLI で CloudHSM CLI でキーの属性を設定する コマンドを使用してキーに一意のラベルを設定することをお勧めします。またはKeyStoreWithAttributes#getKeys、 を使用して、条件に一致するすべてのキーを返します。

すべてのキーを検索する

クライアント SDK 3 では、 を使用して HSM 内のすべてのキーを検索できますUtil.findAllKeys()

クライアント SDK 5 では、 KeyStoreWithAttributes クラスを使用することで、キーの検索がより簡単かつ効率的になります。可能であれば、レイテンシーを最小限に抑えるためにキーをキャッシュします。詳細については、「アプリケーションのキーを効果的に管理する」を参照してください。HSM からすべてのキーを取得する必要がある場合は、空の KeyAttributesMap を指定して KeyStoreWithAttributes#getKeys を使用します。

KeyStoreWithAttributes クラスを使用してキーを検索する例は、AWS CloudHSM GitHub サンプルリポジトリで利用でき、コードスニペットは に示されています1

キー削除

クライアント SDK 3 は Util.deleteKey() を使用してキーを削除します。

クライアント SDK 5 の Key オブジェクトは、このDestroyableインターフェイスの destroy()メソッドを使用してキーを削除できるインターフェイスを実装します。

削除キー機能を示すサンプルコードは、CloudHSM GitHub サンプルリポジトリにあります。各 SDK のサンプルスニペットを 2 に示します。

  • [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 unwrapAES/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
  2. クライアント 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
    注記

    カスタム設定を再度有効にする必要があります。

  3. AWS CloudHSM クライアント SDK 5 の JCE プロバイダーをインストールする」の手順に従って、クライアント SDK JCE プロバイダーをインストールします。

  4. クライアント SDK 5 では、新しい設定ファイル形式とコマンドラインブートストラップツールが導入されました。クライアント SDK 5 JCE プロバイダーをブートストラップするには、ユーザー ガイドの 「クライアント SDK をブートストラップする」に記載されている手順に従ってください。

  5. アプリケーションは開発環境で実行されていること。既存のコードを更新して、最終的な移行前に重大な変更を解決します。

関連トピック