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

# AWS CloudHSM KeyStore 适用于客户端 SDK 的 Java 类 3
<a name="alternative-keystore"></a>

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

**注意**  
由于证书是公共信息，并且为了最大限度地提高加密密钥的存储容量，因此 AWS CloudHSM 不支持在上 HSMs存储证书。

该 AWS CloudHSM `KeyStore`类实现了 Java 密码学扩展 (JCE) 的`KeyStore`服务提供者接口 (SPI)。有关使用的更多信息`KeyStore`，请参阅 C [lass KeyStore](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html)。

## 为 AWS CloudHSM 客户端 SDK 3 选择合适的密钥库
<a name="choosing_keystore"></a>

 AWS CloudHSM Java 加密扩展 (JCE) 提供程序带有默认的直通式只读密钥存储，可将所有交易传递到 HSM。此默认密钥库不同于特殊用途 AWS CloudHSM KeyStore密钥库。在大多数情况下，您将通过使用默认值获得更好的运行时性能和吞吐量。除了将 AWS CloudHSM KeyStore 密钥操作卸载到 HSM 之外，您只应将它用于需要支持证书和基于证书的操作的应用程序。

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

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

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

按如下方式加载特殊用途 KeyStore CloudHSM：

```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```

## AWS CloudHSM KeyStore 为客户端 SDK 初始化 3
<a name="initialize_cloudhsm_keystore"></a>

使用与登录 JCE 提供程序相同的方式登录。 AWS CloudHSM KeyStore 您可以使用环境变量或系统属性文件，并且应该在开始使用 CloudHSM KeyStore 之前登录。有关使用 JCE 提供程序登录 HSM 的示例，请参阅[登录到 HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)。

如果需要，您可以指定密码来加密包含密钥存储数据的本地 PKCS12 文件。创建 AWS CloudHSM 密钥库时，需要设置密码，并在使用加载、设置和获取方法时提供密码。

按如下方式实例化一个新的 CloudHSM 对象 KeyStore ：

```
ks.load(null, null);
```

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

```
ks.load(inputStream, password);
```

## 使用 AWS CloudHSM KeyStore 适用于 AWS CloudHSM 客户端 SDK 3
<a name="using_cloudhsm_keystore"></a>

[https://docs.oracle.com/javase/8/docs/technotes/tools/windows/jarsigner.html](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/jarsigner.html)您也可以直接使用代码访问该对象。

AWS CloudHSM KeyStore 符合 JCE [类KeyStore](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html)规范，并提供以下功能。
+ `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 文件中删除证书条目。不支持使用删除存储在 HSM 中的密钥数据。 AWS CloudHSM KeyStore您可以使用 CloudHSM 的 [key\$1mgmt\$1util](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util.html) 工具删除密钥。
+ `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 上的任何密钥，无论该密钥是否由生成。 KeyStore

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

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

  检查具有给定别名的条目是否表示密钥条目。该操作在 PKCS12 文件和 HSM 中搜索别名。
+ `SetCertificateEntry`

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

  **客户端软件开发工具包 3 目前不支持此 API。**
+ 使用 `Key` 对象执行 `SetKeyEntry`

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

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

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

  返回密钥库中的条目数。
+ `Store`

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