本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
將您的 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 提供者類別稱為 |
在用戶端 SDK 5 中,稱為提供者類別 |
有關如何初始化 |
明確登入已變更,隱含 尚未
已變更的內容 | 用戶端 SDK 3 中的內容 | 用戶端 SDK 5 中的內容 | 範例 |
---|---|---|---|
明確登入 |
用戶端 SDK 3 使用 |
在用戶端 SDK 5 中, |
如需如何搭配用戶端 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 中, |
在用戶端 SDK 5 中, |
如需如何使用 |
金鑰對產生 |
在用戶端 SDK 3 中, |
在用戶端 SDK 5 中, |
如需如何使用 |
-
【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 類型: Cavium
和 CloudHSM
。用戶端 SDK 5 只有一種 KeyStore 類型:CloudHSM
。
從 Cavium
KeyStore 移至 CloudHSM
KeyStore 需要變更 KeyStore 類型。此外,用戶端 SDK 3 使用金鑰控制代碼來參考金鑰,而用戶端 SDK 5 則使用金鑰標籤。產生的行為變更如下所列。
已變更的內容 | 用戶端 SDK 3 中的內容 | 用戶端 SDK 5 中的內容 | 範例 |
---|---|---|---|
金鑰參考 |
透過用戶端 SDK 3,應用程式會使用金鑰標籤或金鑰控點來參考 HSM 中的金鑰。他們使用標籤搭配 KeyStore 來尋找金鑰,或使用控點和建立 |
在用戶端 SDK 5 中,應用程式可以使用 用戶端 SDK 5 的AWS CloudHSM KeyStore Java 類別 依標籤尋找金鑰。若要依控點尋找金鑰,請使用 AWS CloudHSM |
|
尋找多個項目 |
使用 |
使用 AWS CloudHSM |
|
尋找所有金鑰 |
您可以在用戶端 SDK 3 中使用 尋找 HSM 中的所有金鑰 |
用戶端 SDK 5 使用 |
使用 |
金鑰刪除 |
用戶端 SDK 3 使用 |
用戶端 SDK 5 中的 |
您可以在 CloudHSM GitHub 範例儲存庫 |
-
【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 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);
簽章操作尚未變更
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 時選擇不同的平台。
-
解除安裝用戶端 SDK 3 的 JCE 提供者。
-
解除安裝 Client Daemon for Client SDK 3。
注意
需要再次啟用自訂組態。
-
依照中的步驟安裝用戶端 SDK JCE 提供者安裝 AWS CloudHSM 用戶端 SDK 5 的 JCE 提供者。
-
用戶端 SDK 5 推出新的組態檔案格式和命令列引導工具。若要引導您的用戶端 SDK 5 JCE 供應商,請遵循 下使用者指南中列出的說明引導用戶端 SDK。
-
在您的開發環境中,測試您的應用程式。更新現有程式碼,以在最終遷移之前解決重大變更。