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

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

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

使用本主题将您的 JCE 提供程序从客户端 SDK 3 迁移到客户端 SDK 5。有关迁移的好处，请参阅客户端软件开发工具包 5 的优点。

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

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

要查看所有提供商的迁移说明，请参阅从客户端软件开发工具包 3 迁移到客户端软件开发工具包 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 Cloud GitHub H SM LoginRunner 示例存储库中的示例。

隐式登录

隐式登录无需进行任何更改。从客户端 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 CloudHSM 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 中的内容 示例

关键参考文献

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

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

查找多个条目

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

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

找到所有钥匙

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

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

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

删除密钥

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

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

可以在 CloudHSM G ithub 示例存储库中找到显示删除密钥功能的示例代码。中显示了每个 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 加密/解密/封装操作无需进行任何更改。

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。

注意

客户端 SDK 5 目前不支持亚马逊 Linux、Ubuntu 16.04、Ubuntu 18.04 CentOS 6、CentOS 8 和 RHEL 6。如果您目前正在将其中一个平台与客户端 SDK 3 一起使用，则在迁移到客户端 SDK 5 时需要选择其他平台。

  1. 卸载客户端 SDK 的 JCE 提供程序 3。

    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 JCE 提供程序。安装并使用客户端 SDK 5 的 AWS CloudHSM JCE 提供程序

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

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

相关 主题