适用于 Client SDK 3 的 AWS CloudHSM KeyStore Java 类 - AWS CloudHSM
选择密钥库初始化 AWS CloudHSM KeyStore使用 AWS CloudHSM KeyStore

适用于 Client SDK 3 的 AWS CloudHSM KeyStore Java 类

该 AWS CloudHSM KeyStore 类提供了一个特殊用途的 PKCS12 密钥库，允许通过 keytool 和 jarsigner 等应用程序访问 AWS CloudHSM 密钥。该密钥库可以将证书与您的密钥数据一起存储，并将它们与存储在 AWS CloudHSM 上的密钥数据相关联。

注意

由于证书是公共信息，并且为了最大程度地增加加密密钥的存储容量，AWS CloudHSM 不支持在 HSM 上存储证书。

AWS CloudHSM KeyStore 类实现 Java 加密扩展 (JCE) 的 KeyStore 服务提供商接口 (SPI)。有关使用 KeyStore 的更多信息，请参阅 类密钥库。

为 AWS CloudHSM Client SDK 3 选择合适的密钥库

AWS CloudHSM Java 加密扩展（JCE, Java Cryptographic Extension）提供程序附带一个默认的直通、只读密钥库，该密钥库将所有事务传递给 HSM。此默认密钥库不同于专用的 AWS CloudHSM 密钥库。在大多数情况下，您将通过使用默认值获得更好的运行时性能和吞吐量。除了将密钥操作分载到 HSM 之外，您仅应将 AWS CloudHSM 密钥库用于需要支持证书和基于证书的操作的应用程序。

尽管两个密钥库都使用 JCE 提供程序执行操作，但是它们是独立的实体，并且彼此之间不交换信息。

为您的 Java 应用程序加载默认密钥库，如下所示：

KeyStore ks = KeyStore.getInstance("Cavium");

加载专用的 CloudHSM 密钥库，如下所示：

KeyStore ks = KeyStore.getInstance("CloudHSM")

初始化 Client SDK 3 的 AWS CloudHSM KeyStore

登录 AWS CloudHSM 密钥库的方式与您登录 JCE 提供程序的方式相同。您可以使用环境变量或系统属性文件，并且应该在开始使用 CloudHSM 密钥库之前登录。有关使用 JCE 提供程序登录 HSM 的示例，请参阅登录到 HSM。

如果需要，您可以指定密码以加密保存密钥库数据的本地 PKCS12 文件。创建 AWS CloudHSM 密钥库时，您可以设置密码并在使用 load、set 和 get 方法时提供该密码。

实例化一个新的 CloudHSM 密钥库对象，如下所示：

ks.load(null, null);

使用 store 方法将密钥库数据写入文件。从那时起，您可以使用带有源文件和密码的 load 方法加载现有密钥库，如下所示：

ks.load(inputStream, password);

使用适用于 AWS CloudHSM Client SDK 3 的 AWS CloudHSM KeyStore

CloudHSM 密钥库对象通常通过第三方应用程序（如 jarsigner 或 keytool）使用。您也可以直接使用代码访问该对象。

AWS CloudHSM 密钥库符合 JCE 类密钥库规范，并提供以下函数。

  • load

    从给定输入流加载密钥库。如果在保存密钥库时设置了密码，则必须提供相同的密码才能成功加载。将两个参数都设置为 null 可以初始化一个新的空密钥库。

    KeyStore ks = KeyStore.getInstance("CloudHSM");
ks.load(inputStream, password);

  • aliases

    返回给定密钥库实例中所有条目的别名的枚举。结果包括本地存储在 PKCS12 文件中的对象和驻留在 HSM 上的对象。

    示例代码：

    KeyStore ks = KeyStore.getInstance("CloudHSM");
for(Enumeration<String> entry = ks.aliases(); entry.hasMoreElements();) 
	{    
		String label = entry.nextElement();    
		System.out.println(label);
	}

  • ContainsAlias

    如果密钥库可以访问至少一个具有指定别名的对象，则返回 true。密钥库检查本地存储在 PKCS12 文件中的对象和驻留在 HSM 上的对象。

  • DeleteEntry

    从本地 PKCS12 文件中删除证书条目。不支持使用 AWS CloudHSM 密钥库删除存储在 HSM 中的密钥数据。您可以使用 CloudHSM 的 key_mgmt_util 工具删除密钥。

  • GetCertificate

    返回与别名关联的证书（如果可用）。如果别名不存在或引用的对象不是证书，则该函数返回 NULL。

    KeyStore ks = KeyStore.getInstance("CloudHSM");
Certificate cert = ks.getCertificate(alias)

  • GetCertificateAlias

    返回其数据与给定证书匹配的第一个密钥库条目的名称（别名）。

    KeyStore ks = KeyStore.getInstance("CloudHSM");
String alias = ks.getCertificateAlias(cert)

  • GetCertificateChain

    返回与给定别名关联的证书链。如果别名不存在或引用的对象不是证书，则该函数返回 NULL。

  • GetCreationDate

    返回由给定别名标识的条目的创建日期。如果创建日期不可用，则函数返回证书生效的日期。

  • GetKey

    GetKey 被传递给 HSM，并返回一个与给定标签对应的密钥对象。当 getKey 直接查询 HSM 时，它可以用于 HSM 上的任何密钥，无论它是否由密钥库生成都是如此。

    Key key = ks.getKey(keyLabel, null);

  • IsCertificateEntry

    检查具有给定别名的条目是否表示证书条目。

  • IsKeyEntry

    检查具有给定别名的条目是否表示密钥条目。该操作同时搜索 PKCS12 文件和 HSM 以查找别名。

  • SetCertificateEntry

    将给定证书分配给给定别名。如果给定的别名已被用于标识密钥或证书，则会引发 KeyStoreException。您可以使用 JCE 代码获取密钥对象，然后使用密钥库 SetKeyEntry 方法将证书与密钥关联。

  • 使用 byte[] 密钥执行 SetKeyEntry

    客户端软件开发工具包 3 目前不支持此 API。

  • 使用 Key 对象执行 SetKeyEntry

    将给定密钥分配到给定别名并将其存储在 HSM 中。如果 Key 对象不属于类型 CaviumKey，则该密钥将作为可提取会话密钥导入到 HSM 中。

    如果 Key 对象属于类型 PrivateKey，则它必须伴随相应的证书链。

    如果别名已存在，则 SetKeyEntry 调用会引发 KeyStoreException，并阻止该密钥被覆盖。如果密钥必须被覆盖，请为此目的使用 KMU 或 JCE。

  • EngineSize

    返回密钥库中的条目数。

  • Store

    将密钥库存储作为 PKCS12 文件存储到给定输出流，并使用给定的密码保护它。此外，它会保留所有加载的密钥（使用 setKey 调用进行设置）。