本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 用戶端 SDK 5 的AWS CloudHSM KeyStore Java 類別
<a name="alternative-keystore_5"></a>

 AWS CloudHSM `KeyStore` 類別提供特殊用途的 PKCS12 金鑰存放區。此金鑰存放區可與您的金鑰資料一起儲存憑證，並將其與在 AWS CloudHSM儲存的金鑰資料連結在一起。`KeyStore` 類別實作 Java AWS CloudHSM 密碼編譯延伸 (JCE) 的`KeyStore`服務提供者界面 (SPI)。如需使用 `KeyStore` 的詳細資訊，請參閱 [Class KeyStore](https://devdocs.io/openjdk~8/java/security/keystore)。

**注意**  
由於憑證是公有資訊，且為了最大化密碼編譯金鑰的儲存容量， AWS CloudHSM 不支援在 HSMs上儲存憑證。

## 為 AWS CloudHSM 用戶端 SDK 5 選擇適當的金鑰存放區
<a name="choosing_keystore_5"></a>

 AWS CloudHSM Java 密碼編譯延伸 (JCE) 供應商提供特殊用途的 AWS CloudHSM KeyStore。 AWS CloudHSM `KeyStore` 類別支援將金鑰操作卸載至 HSM、本機儲存憑證和憑證型操作。

載入特殊用途的 CloudHSM 金鑰存放區，如下所示：

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

## 初始化 AWS CloudHSM KeyStore 用戶端 SDK 5
<a name="initialize_cloudhsm_keystore_5"></a>

以與登入 JCE 提供者相同的方式登入 AWS CloudHSM KeyStore。您可以使用環境變數或系統屬性檔案，並且在開始使用 CloudHSM 金鑰存放區之前應先登入。如需使用 JCE 提供者登入 HSM 的範例，請參閱[登入 HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)。

如有需要，您可以指定一組密碼來加密保存金鑰儲存資料的本機 PKCS12 檔案。當您建立 AWS CloudHSM 金鑰存放區時，您可以設定密碼，並在使用載入、設定和取得方法時提供密碼。

請依照以下方式，將新的 CloudHSM 金鑰存放區物件執行個體化：

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

使用 `store` 方法將金鑰存放區資料寫入檔案。從那時起，您可以依照以下方式，搭配來源檔案和密碼使用 `load` 方法載入現有的金鑰存放區：

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

## Use AWS CloudHSM KeyStore 或 AWS CloudHSM 用戶端 SDK 5
<a name="using_cloudhsm_keystore_5"></a>

AWS CloudHSM KeyStore 符合 JCE [類別 KeyStore](https://devdocs.io/openjdk~8/java/security/keystore) 規格，並提供下列函數。
+ `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 KeyStore 刪除存放在 HSM 中的金鑰資料。您可以使用[可銷毀](https://devdocs.io/openjdk~8/javax/security/auth/destroyable#destroy--)介面 `destroy` 的銷毀方法刪除金錀。

  ```
  ((Destroyable) key).destroy();
  ```
+ `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`

  **用戶端 SDK 5 目前不支援此 API。**
+ 有 `Key` 物件的 `setKeyEntry`

  指定特定金鑰至特定別名，並將其儲存在 HSM 內。如果該金鑰未儲存在 HSM 內，則該金錀將做為可擷取的工作階段金鑰匯入至 HSM。

  如果 `Key` 物件屬於類型 `PrivateKey`，則必須附有相對應的憑證鏈。

  如果別名已經存在，則 `SetKeyEntry` 呼叫會擲出 `KeyStoreException` 並防止覆寫金鑰。如果必須覆寫金鑰，請使用 KMU 或 JCE。
+ `engineSize`

  傳回金鑰存放區中的項目數目。
+ `store`

  以 PKCS12 檔案格式儲存金鑰存放區至特定輸出串流，並使用特定的密碼加以保護。此外，它仍然保留載入的金鑰 (使用 `setKey` 呼叫的組合)。