JCE プロバイダーをクライアント SDK 3 からクライアント SDK 5 に移行する - AWS CloudHSM
重大な変更に対処して準備するClient SDK 5 への移行 関連トピック

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

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

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

では AWS CloudHSM、顧客アプリケーションは AWS CloudHSM クライアントソフトウェア開発キット (SDK) を使用して暗号化オペレーションを実行します。Client SDK 5 は、引き続き新機能とプラットフォームサポートが追加されているプライマリ SDK です。

Client SDK 3 JCE プロバイダーは、標準 JCE 仕様に含まれていないカスタムクラスと APIs を使用します。JCE プロバイダーのクライアント SDK 5 は JCE 仕様に準拠しており、特定の領域ではクライアント SDK 3 と下位互換性がありません。お客様のアプリケーションでは、クライアント SDK 5 への移行の一環として変更が必要になる場合があります。このセクションでは、移行を成功させるために必要な変更点の概要を説明します。

すべてのプロバイダーの移行手順を確認するには、「」を参照してくださいClient SDK 3 から Client SDK 5 への移行。

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

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

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

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

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

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

クライアント SDK 5 では、プロバイダークラス が呼び出CloudHsmProviderされ、プロバイダー名は ですCloudHSM。

CloudHsmProvider オブジェクトを初期化する方法の例は、AWS CloudHSM GitHub サンプルリポジトリ にあります。

明示的なログインが変更されましたが、暗黙的な は変更されていません

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

明示的なログイン

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

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

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

暗黙的なログイン

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

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

  • [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);

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

表示を増やす表示を減らす

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

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

キー生成

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

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

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

キーペアの生成

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

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

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

  • [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();
表示を増やす表示を減らす

キーの検索、削除、参照が変更されました

AWS CloudHSM を使用して、 で既に生成されたキーを検索する KeyStore。Client SDK 3 には、 Caviumと の 2 つの KeyStore タイプがありますCloudHSM。クライアント SDK 5 には KeyStore 、タイプ が 1 つだけありますCloudHSM。

から Cavium KeyStore に移行するには、 KeyStore タイプの変更CloudHSM KeyStore が必要です。さらに、クライアント SDK 3 はキーを参照するためにキーハンドルを使用し、クライアント SDK 5 はキーラベルを使用します。結果として生じる動作の変更を以下に示します。

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

キーリファレンス

Client SDK 3 では、アプリケーションはキーラベルまたはキーハンドルを使用して HSM 内のキーを参照します。でラベルを使用してキー KeyStore を検索するか、ハンドルを使用してCaviumKeyオブジェクトを作成します。

Client SDK 5 では、アプリケーションは を使用してラベルでキーAWS CloudHSM KeyStore Java クラスの使用を検索できます。ハンドルでキーを検索するには、 AWS CloudHSM KeyStoreWithAttributesで を使用します AWS CloudHSM KeyRefereneSpec。

複数のエントリの検索

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

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

すべてのキーを検索する

Client SDK 3 では、 を使用して HSM 内のすべてのキーを検索できますUtil.findAllKeys()。

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

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

キー削除

Client SDK 3 は Util.deleteKey() を使用してキーを削除します。

Client 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] Client SDK 3 でキーを削除する：

    Util.deleteKey(key);

    Client SDK 5 でキーを削除する：

    ((Destroyable) key).destroy();
表示を増やす表示を減らす

暗号アンラップオペレーションが変更され、他の暗号オペレーションは変更されていません

注記

暗号の暗号化/復号/ラップオペレーションに変更は必要ありません。

アンラップオペレーションでは、Client SDK 3 CaviumUnwrapParameterSpec クラスを、リストされている暗号化オペレーションに固有の次のいずれかのクラスに置き換える必要があります。

  • GCMUnwrapKeySpec AES/GCM/NoPaddingアンラップ用

  • IvUnwrapKeySpec AESWrap unwrapおよび 用 AES/CBC/NoPadding unwrap

  • 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);
表示を増やす表示を減らす

署名オペレーションが変更されていない

署名オペレーションに変更は必要ありません。

Client SDK 5 への移行

このセクションの手順に従って、Client SDK 3 から Client SDK 5 に移行します。

注記

Amazon Linux、Ubuntu 16.04、Ubuntu 18.04 CentOS 6、CentOS 8、および RHEL 6 は現在、クライアント SDK 5 ではサポートされていません。現在、クライアント SDK 3 でこれらのプラットフォームのいずれかを使用している場合は、クライアント SDK 5 に移行するときに別のプラットフォームを選択する必要があります。

  1. Client SDK 3 の JCE プロバイダーをアンインストールします。

    Amazon Linux 2
    $ sudo yum remove cloudhsm-jce
    CentOS 7
    $ sudo yum remove cloudhsm-jce
    RHEL 7
    $ sudo yum remove cloudhsm-jce
    RHEL 8
    $ sudo yum remove cloudhsm-jce

  2. Client SDK 3 のクライアントデーモンをアンインストールします。

    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. 「」の手順に従って、クライアント SDK JCE プロバイダーをインストールしますClient SDK 5 の AWS CloudHSM JCE プロバイダーをインストールして使用する。

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

  5. 開発環境で、アプリケーションをテストします。既存のコードを更新して、最終的な移行前に重大な変更を解決します。

関連トピック