选择您的 Cookie 首选项

我们使用必要 Cookie 和类似工具提供我们的网站和服务。我们使用性能 Cookie 收集匿名统计数据，以便我们可以了解客户如何使用我们的网站并进行改进。必要 Cookie 无法停用，但您可以单击“自定义”或“拒绝”来拒绝性能 Cookie。

如果您同意，AWS 和经批准的第三方还将使用 Cookie 提供有用的网站功能、记住您的首选项并显示相关内容，包括相关广告。要接受或拒绝所有非必要 Cookie，请单击“接受”或“拒绝”。要做出更详细的选择，请单击“自定义”。

首选项
联系我们
反馈
AWS Documentation
创建 AWS 账户

将您的 JCE 提供程序从 AWS CloudHSM 客户端 SDK 3 迁移到客户端 SDK 5

PDF
RSS
聚焦模式
将您的 JCE 提供程序从 AWS CloudHSM 客户端 SDK 3 迁移到客户端 SDK 5 - AWS CloudHSM
通过解决重大更改做好准备迁移到 Client SDK 5相关 主题

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

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

使用本主题将您的 JCE 提供程序从 AWS CloudHSM Client SDK 3 迁移到 Client SDK 5。有关迁移的好处，请参阅 AWS CloudHSM 客户 SDK 5 的好处。

在中 AWS CloudHSM，客户应用程序使用 AWS CloudHSM 客户端软件开发套件 (SDK) 执行加密操作。Client SDK 5 是主要 SDK，它不断添加新功能和平台支持。

客户端 SDK 3 JCE 提供程序使用自定义类 APIs ，这些类不属于标准 JCE 规范。JCE 提供程序的 Client SDK 5 不符合 JCE 规范，并且在某些方面与 Client SDK 3 向后不兼容。在迁移到 Client SDK 5 的过程中，可能需要对客户应用程序进行更改。本节概述了成功迁移所需的更改。

要查看所有提供程序的迁移说明，请参阅 从 AWS CloudHSM 客户端 SDK 3 迁移到客户端 SDK 5。

通过解决重大更改做好准备

查看这些重大更改，并在开发环境中相应地更新您的应用程序。

提供程序类和名称已更改

已更改的内容 Client SDK 3 中的内容 Client SDK 5 中的内容 示例

提供程序类和名称

Client SDK 3 中的 JCE 提供程序类称为 CaviumProvider，提供程序名称为 Cavium。

在 Client SDK 5 中，提供程序类称为 CloudHsmProvider，提供程序名称为 CloudHSM。

示例存储库中提供了如何初始化CloudHsmProvider对象的AWS CloudHSM GitHub 示例。

显式登录已更改，隐式登录未更改

已更改的内容 Client SDK 3 中的内容 Client SDK 5 中的内容 示例

显式登录

Client SDK 3 使用 LoginManager 类进行显式登录 1。

在 Client SDK 5 中，CloudHSM 提供程序实现 AuthProvider 来进行显式登录。AuthProvider 是一个标准 Java 类，它遵循 Java 的惯用方式登录提供程序。借助 Client SDK 5 中改进的登录状态管理，应用程序不再需要在重新连接期间监控和执行登录2。

有关如何在客户端软件开发工具包 5 中使用显式登录的示例，请参阅 AWS Cloud GitHub H SM LoginRunner 示例存储库中的示例。

隐式登录

隐式登录无需进行任何更改。从 Client SDK 3 迁移到 Client SDK 5 时，相同的属性文件和所有环境变量将继续适用于隐式登录。

有关如何在 Client SDK 5 中使用隐式登录的示例，请参阅LoginRunner 示例存储库中的 AWS CloudHSM GitHub 示例。

  • [1] Client SDK 3 代码片段：

    LoginManager lm = LoginManager.getInstance();
                       
lm.login(partition, user, pass);

  • [2] Client 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 示例。

密钥生成已更改

已更改的内容 Client SDK 3 中的内容 Client SDK 5 中的内容 示例

密钥生成

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

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

有关如何使用KeyAttributesMap生成对称密钥的示例，请参阅 AW GitHub S CloudHSM SymmetricKeys 示例存储库中的示例。

密钥对生成

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

在 Client SDK 5 中，KeyPairAttributesMap 用于指定这些参数。有关代码片段，请参阅脚注 4。

有关如何使用KeyAttributesMap生成非对称密钥的示例，请参阅AsymmetricKeys 示例存储库中的 AWS CloudHSM GitHub 示例。

  • [1] Client SDK 3 密钥生成代码片段：

    KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec aesSpec = new CaviumAESKeyGenParameterSpec(
keySizeInBits,
keyLabel,
isExtractable,
isPersistent);
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();

  • [2] Client 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] Client 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] Client 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 类型。此外，Client SDK 3 使用密钥句柄来引用密钥，而 Client SDK 5 使用密钥标签。下面列出了由此产生的行为更改。

已更改的内容 Client SDK 3 中的内容 Client SDK 5 中的内容 示例

密钥引用

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

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

查找多个条目

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

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

查找所有密钥

在 Client SDK 3 中，可以使用 Util.findAllKeys() 查找 HSM 中的所有密钥。

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

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

删除密钥

Client SDK 3 使用 Util.deleteKey() 删除密钥。

Client SDK 5 中的 Key 对象实现了 Destroyable 接口，这样做允许使用此接口的 destroy() 方法删除密钥。

在 Cloud GitHub HSM 示例存储库中可以找到显示删除密钥功能的示例代码。2 中显示了每个 SDK 的示例片段。

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

密码解包操作已更改，其他密码操作未更改

注意

Cipher encrypt/decrypt/wrap 操作无需进行任何更改。

解包操作需要将 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。

注意

Client SDK 5 当前不支持 Amazon Linux、Ubuntu 16.04、Ubuntu 18.04 CentOS 6、CentOS 8 和 RHEL 6。如果您当前正在将其中一个平台与 Client SDK 3 结合使用，则在迁移到 Client SDK 5 时，您需要选择其他平台。

  1. 卸载 Client 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
    anchoranchoranchoranchor
    $ sudo yum remove cloudhsm-client-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
    anchoranchoranchoranchor
    $ sudo yum remove cloudhsm-client
    注意

    需要再次启用自定义配置。

  3. 按照 为 AWS CloudHSM 客户端 SDK 5 安装 JCE 提供程序 中的步骤安装 Client SDK JCE 提供程序。

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

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

相关 主题

本页内容

隐私网站条款Cookie 首选项
© 2025, Amazon Web Services, Inc. 或其附属公司。保留所有权利。