将您的JCE提供商从 AWS CloudHSM 客户端 SDK 3 迁移到客户端 SDK 5 - AWS CloudHSM
通过解决重大变化做好准备迁移到客户端 SDK 5相关 主题

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

将您的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 是继续添加新功能和平台支持的主要客户端。

Client SDK 3 JCE 提供程序使用自定义类APIs，这些类不属于标准JCE规范。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期间监控和执行登录。

有关如何在 Client SDK 5 上使用显式登录的示例，请参阅 AWSCloud LoginRunner HSM GitHub 示例存储库中的示例。

隐式登录

对于隐式登录，无需进行任何更改。从客户端 SDK 3 迁移到客户端 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 中的内容 客户端 SDK 5 中的内容 示例

密钥生成

在客户端 SDK 3 中，Cavium[Key-type]AlgorithmParameterSpec用于指定密钥生成参数。有关代码片段，请参阅脚注1。

在客户端 SDK 5 中，KeyAttributesMap用于指定密钥生成属性。有关代码片段，请参阅脚注2。

有关如何使用KeyAttributesMap生成对称密钥的示例，请参阅 AWS Cloud HSM Github SymmetricKeys 示例存储库中的示例。

密钥对生成

在客户端 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 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。

从移动Cavium KeyStore 到CloudHSM KeyStore 需要更改 KeyStore 类型。此外，客户端 SDK 3 使用按键手柄来引用密钥，而客户端 SDK 5 使用按键标签。下面列出了由此产生的行为变化。

发生了什么变化 客户端 SDK 3 中的内容 客户端 SDK 5 中的内容 示例

关键参考文献

在客户端 SDK 3 中，应用程序使用按键标签或按键手柄来引用中的密钥HSM。他们使用标签 KeyStore 来查找钥匙，或者他们使用手柄创建CaviumKey对象。

在客户端 SDK 5 中，应用程序可以使用AWS CloudHSM KeyStore 客户端 SDK 5 的 Java 类按标签查找密钥。要按手柄查找按键，请 AWS CloudHSM KeyStoreWithAttributes使用 with AWS CloudHSM KeyRefereneSpec。

查找多个条目

使用getEntry、或搜索密钥时getKey，如果getCertificate中存在多个具有相同条件的项目 Cavium KeyStore，则只会返回找到的第一个条目。

使用 AWS CloudHSM KeyStore和KeyStoreWithAttributes，同样的场景将导致引发异常。要解决此问题，建议在 Cloud 中使用使用 Cloud 设置密钥的属性 HSM CLI命令为密钥设置唯一标签HSMCLI。或者使用KeyStoreWithAttributes#getKeys返回所有符合条件的密钥。

找到所有钥匙

在客户端 SDK 3 中可以找到HSM使用中的所有密钥Util.findAllKeys()。

通过使用该KeyStoreWithAttributes类，客户端 SDK 5 使查找密钥变得更简单、更高效。如果可能，请缓存您的密钥以最大限度地减少延迟。有关更多信息，请参阅 有效管理应用程序中的密钥。当你需要从中检索所有密钥时HSM，请KeyStoreWithAttributes#getKeys使用空的KeyAttributesMap。

AWS CloudHSM Github 示例存储库中提供了使用该KeyStoreWithAttributes类查找密钥的示例，其中显示了一个代码片段。1

删除密钥

客户端 SDK 3 Util.deleteKey() 用来删除密钥。

客户端 SDK 5 中的Key对象实现了允许使用该Destroyable接口的destroy()方法删除密钥的接口。

可以在 C loud HSM 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 操作无需进行任何更改。

Unwrap 操作要求将 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 目前不支持亚马逊 Linux、Ubuntu 16.04、Ubuntu 18.04 CentOS 6、CentOS 8 和 6。RHEL SDK如果您当前在客户端 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. 按照中的步骤安装客户端SDKJCE提供程序安装 AWS CloudHSM 客户端 SDK 5 的JCE提供程序。

  4. 客户端 SDK 5 引入了新的配置文件格式和命令行引导工具。要引导您的 Client SDK 5 JCE 提供商，请按照用户指南中列出的说明进行操作。引导客户端 SDK

  5. 在您的开发环境中，测试您的应用程序。在最终迁移之前，请更新现有代码以解决重大更改。

相关 主题