將您的 JCE 提供者從用戶端 SDK 3 遷移到用戶端 SDK 5 - AWS CloudHSM
通過解決突破性更改做好遷移至用戶端 SDK 5相關主題

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

將您的 JCE 提供者從用戶端 SDK 3 遷移到用戶端 SDK 5

使用本主題可將您的 JCE 提供者從用戶端 SDK 3 遷移至用戶端 SDK 5。如需移轉的優點，請參閱用戶端 SDK 5 的優點 。

在中 AWS CloudHSM，客戶應用程式會使用用戶 AWS CloudHSM 端軟體開發套件 (SDK) 執行密碼編譯作業。客戶端 SDK 5 是繼續添加新功能和平台支持的主要 SDK。

用戶端 SDK 3 JCE 提供者使用不屬於標準 JCE 規格一部分的自訂類別和 API。JCE 提供商的客戶端 SDK 5 對 JCE 規範抱怨，並且在某些區域與客戶端 SDK 3 向後不兼容。在遷移至用戶端 SDK 5 時，客戶應用程式可能需要進行變更。本節概述成功移轉所需的變更。

若要檢閱所有提供者的移轉指示，請參閱從用戶端 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 的慣用方式登錄到提供程序。在 Client SDK 5 中改進了登錄狀態管理，應用程序不再需要在重新連接2期間監視和執行登錄。

如需如何透過用戶端開發套件 5 使用明確登入的範例，請參閱 AWS CloudHSM LoginRunner 範例儲存庫中的 GitHub 範例。

隱式登入

隱含登入不需要變更。從客戶端 SDK 3 遷移到客戶端 SDK 5 時，相同的屬性文件和所有環境變量將繼續適用於隱式登錄。

如需如何搭配用戶端 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 中是什麼 它是什麼在客戶端 SDK 5 範例

金鑰產生

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

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

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

產生金鑰配對

在用戶端 SDK 3 中，用Cavium[Key-type]AlgorithmparameterSpec於指定 key pair 產生參數。如需程式碼片段，請參閱註腳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 key pair 生成代碼片段：：

    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 key pair 生成代碼片段：

    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 種類型：Cavium和CloudHSM. 用戶端 SDK 5 只有一 KeyStore 種類型：CloudHSM。

從到移動CloudHSM KeyStore 需Cavium KeyStore 要變更類 KeyStore 型。此外，用戶端 SDK 3 會使用金鑰控制點來參考金鑰，而用戶端 SDK 5 則使用金鑰標籤。產生的行為變更如下所示。

發生了什麼變化 它在客戶端 SDK 3 中是什麼 它是什麼在客戶端 SDK 5 範例

關鍵參考

在用戶端 SDK 3 中，應用程式會使用金鑰標籤或金鑰控制點來參考 HSM 中的金鑰。他們使用標籤 KeyStore 來查找鍵，或者他們使用控點和創建CaviumKey對象。

在用戶端 SDK 5 中，應用程式可以如 AWS CloudHSM KeyStore 何使用 Java 類別使用按標籤尋找金鑰。若要依控制點尋找金鑰，請使用 AWS CloudHSM KeyStoreWithAttributes與 AWS CloudHSM KeyRefereneSpec。

尋找多個項目

當使用getEntry、或搜尋金鑰時getKey，如果getCertificate中存在多個具有相同文字的項目 Cavium KeyStore，則只會傳回找到的第一個項目。

使用 AWS CloudHSM KeyStore和KeyStoreWithAttributes，這個相同的情況將導致拋出異常。若要修正此問題，建議您使用 CloudHSM CLI 中的設定金錀屬性命令為金鑰設定唯一標籤。或者使用KeyStoreWithAttributes#getKeys返回與該密鑰匹配的所有鍵。

尋找所有金鑰

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

客戶端 SDK 5 使得通過使用KeyStoreWithAttributes類更簡單，更有效地查找密鑰。如果可能，請快取金鑰以將延遲降至最低。如需詳細資訊，請參閱 有效管理應用程式中的金鑰。當您需要從 HSM 擷取所有金鑰時，請使KeyStoreWithAttributes#getKeys用空白KeyAttributesMap金鑰。

AWS CloudHSM Github 範例儲存庫中提供了使用KeyStoreWithAttributes類別尋找金鑰的範例，並在中顯示程式碼片段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();
顯示較多顯示較少

密碼解包操作已更改，其他密碼操作沒有

注意

無需更改密碼加密/解密/包裝操作。

解除換行作業需要將 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);
顯示較多顯示較少

簽章作業未變更

簽名操作不需要進行任何變更。

遷移至用戶端 SDK 5

請遵循本節中的指示，從用戶端 SDK 3 遷移至用戶端 SDK 5。

注意

用戶端軟體開發套件 5 目前不支援 Amazon Linux、Ubuntu 18.04 CentOS 6、CentOS 8 及 RHEL 6。如果您目前正在搭配用戶端 SDK 3 使用其中一個平台，則在移轉至用戶端 SDK 5 時，必須選擇不同的平台。

  1. 解除安裝用戶端 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. 解除安裝用戶端 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 5 的 AWS CloudHSM JCE 提供者的步驟安裝用戶端 SDK JCE 提供者。

  4. 客戶端 SDK 5 引入了新的配置文件格式和命令行引導工具。若要啟動用戶端 SDK 5 JCE 提供者，請遵循使用者指南中列出的引導用戶端 SDK指示。

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

相關主題