將您的 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 規格的自訂類別和 APIs。適用於 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 使用 LoginManager類別進行明確登入 1

在用戶端 SDK 5 中,CloudHSM提供者會實作 AuthProvider 以進行明確登入。 AuthProvider 是標準 Java 類別,並遵循 Java 的慣用方式登入提供者。透過改善用戶端 SDK 5 中的登入狀態管理,應用程式不再需要在重新連線期間監控和執行登入2

如需如何搭配用戶端 SDK 5 使用明確登入的範例,請參閱 AWS CloudHSM GitHub 範例儲存庫中的 LoginRunner 範例。 AWS CloudHSM GitHub

隱含登入

不需要變更即可進行隱含登入。從用戶端 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

在用戶端 SDK 5 中, KeyAttributesMap 用於指定金鑰產生屬性。如需程式碼片段,請參閱註腳 2

如需如何使用 KeyAttributesMap產生對稱金鑰的範例,請參閱 AWS CloudHSM GitHub 範例儲存庫中的 SymmetricKeys 範例。

金鑰對產生

在用戶端 SDK 3 中, Cavium[Key-type]AlgorithmparameterSpec 用於指定金鑰對產生參數。如需程式碼片段,請參閱註腳 3

在用戶端 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();

尋找、刪除和參考金鑰已變更

AWS CloudHSM 使用 KeyStore 尋找已產生的金鑰。用戶端 SDK 3 有兩種 KeyStore 類型: CaviumCloudHSM。用戶端 SDK 5 只有一種 KeyStore 類型:CloudHSM

Cavium KeyStore 移至 CloudHSM KeyStore 需要變更 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

尋找多個項目

使用 getEntrygetKeygetCertificate 在 KeyStore 中存在多個條件相同的項目的情況下搜尋Cavium金鑰時,只會傳回找到的第一個項目。

使用 AWS CloudHSM KeyStore和 時KeyStoreWithAttributes,此相同案例會導致擲回例外狀況。若要修正此問題,建議您使用 CloudHSM CLI 中的 使用 CloudHSM CLI 設定金鑰的屬性命令來設定金鑰的唯一標籤。或使用 KeyStoreWithAttributes#getKeys 傳回符合條件的所有金鑰。

尋找所有金鑰

您可以在用戶端 SDK 3 中使用 尋找 HSM 中的所有金鑰Util.findAllKeys()

用戶端 SDK 5 使用 KeyStoreWithAttributes類別,讓問題清單索引鍵變得更簡單、更有效率。可能的話,請快取您的金鑰,將延遲降至最低。如需詳細資訊,請參閱有效管理應用程式中的金鑰。當您需要從 HSM 擷取所有金鑰時,請使用 KeyStoreWithAttributes#getKeys搭配空的 KeyAttributesMap

使用 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 encrypt/decrypt/wrap 操作不需要變更。

取消包裝操作需要將用戶端 SDK 3 CaviumUnwrapParameterSpec類別取代為下列密碼編譯操作專用的其中一個類別。

  • GCMUnwrapKeySpec 用於AES/GCM/NoPadding取消包裝

  • IvUnwrapKeySpec 適用於 AESWrap unwrapAES/CBC/NoPadding unwrap

  • 適用於 RSA OAEP unwrapOAEPUnwrapKeySpec

的範例程式碼片段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);

簽章操作尚未變更

Signature 操作不需要變更。

遷移至用戶端 SDK 5

遵循本節中的指示,從用戶端 SDK 3 遷移到用戶端 SDK 5。

注意

用戶端 SDK 5 目前不支援 Amazon Linux、Ubuntu 16.04、Ubuntu 18.04 CentOS 6、CentOS 8 和 RHEL 6。如果您目前使用其中一個平台搭配用戶端 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. 解除安裝 Client Daemon for 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 提供者安裝 AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者

  4. 用戶端 SDK 5 推出新的組態檔案格式和命令列引導工具。若要引導您的用戶端 SDK 5 JCE 供應商,請遵循 下使用者指南中列出的說明引導用戶端 SDK

  5. 在您的開發環境中,測試您的應用程式。更新現有程式碼,以在最終遷移之前解決重大變更。

相關主題