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

# AWS CloudHSM 用戶端 SDK 5 支援的 Java 金鑰屬性
<a name="java-lib-attributes_5"></a>

本主題提供有關 AWS CloudHSM 用戶端 SDK 5 支援的 Java 金鑰屬性的資訊。本主題說明如何使用 JCE 提供程序的專屬擴充功能來設定金鑰屬性。請在以下操作期間，使用此擴充功能來設定支援的金鑰屬性及其值：
+ 金鑰產生
+ 金鑰匯入

如需如何使用金錀屬性的範例，請參閱 [Java for Client SDK 5 AWS CloudHSM 軟體程式庫的程式碼範例](java-samples.md)。

**Topics**
+ [了解屬性](#java-understanding-attributes_5)
+ [支援的屬性](#java-attributes_5)
+ [設定金鑰的屬性](#java-setting-attributes_5)

## 了解屬性
<a name="java-understanding-attributes_5"></a>

使用金鑰屬性來指定金鑰物件上允許的動作，包括公有金鑰、私有金鑰或秘密金鑰。在建立金鑰物件操作期間定義金鑰屬性和值。

Java Cryptography Extension (JCE) 未指定應該如何設定金鑰屬性的值，因此預設情況下會允許大部分動作。相反地，PKCS\$111 標準定義了一組具有更嚴格預設值的完整屬性。從 JCE 提供者 3.1 開始， AWS CloudHSM 提供專屬擴充功能，可讓您為常用屬性設定更嚴格的值。

## 支援的屬性
<a name="java-attributes_5"></a>

您可以設定下表中屬性的值。最佳實務是，只為您希望更具有限制性的屬性設定值。如果您未指定值， AWS CloudHSM 會使用下表中指定的預設值。預設值欄位中的空白儲存格表示屬性沒有獲派指定預設值。


****  

| 屬性 | 預設值 | 備註 |  | 對稱金鑰 | 金鑰對中的公有金鑰 | 金鑰對中的私有金鑰 |  | 
| --- | --- | --- | --- | --- | --- | --- | --- | 
| DECRYPT | TRUE |  | TRUE | True 表示您可以使用金鑰來解密任何緩衝區。對於其 WRAP 設定為 true 的金鑰，通常將此設定為 FALSE。 | 
| DERIVE |  |  |  | 可以使用金鑰來衍生其他金鑰。 | 
| ENCRYPT | TRUE | TRUE |  | True 表示您可以使用金鑰來加密任何緩衝區。 | 
| EXTRACTABLE | TRUE |  | TRUE | True 表示您可以從 HSM 匯出此金鑰。 | 
| ID |  |  |  | 用於識別金鑰的使用者定義值。 | 
| KEY\$1TYPE |  |  |  | 用於識別金鑰的類型 (AES、DESede、一般私密錦綸、EC 或 RSA)。 | 
| LABEL |   |  |  | 使用者定義的字串可方便您識別 HSM 上的金鑰。為了遵循最佳實務，請為每個金鑰使用唯一標籤，以便日後更容易找到。 | 
| LOCAL |  |  |  | 表示 HSM 產生的金鑰。 | 
| OBJECT\$1CLASS |  |  |  | 用於識別金錀 (SecretKey、PublicKey 或 PrivateKey) 的物件類別。 | 
| PRIVATE | TRUE | TRUE | TRUE | True 表示在使用者通過驗證之前，使用者可能無法存取金鑰。為了清楚起見，使用者必須經過身分驗證 AWS CloudHSM 才能存取 上的任何金鑰，即使此屬性設為 FALSE。 | 
| SIGN | TRUE |  | TRUE | True 表示您可以使用金鑰來簽署訊息摘要。對於公有金鑰和您已封存的私有金鑰，這通常會設定為 FALSE。 | 
| SIZE |  |  |  | 定義金錀大小的屬性。如需有關支援金鑰大小的詳細資訊，請參閱[用戶端 SDK 5 的支援機制](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-lib-supported_5.html#java-keys_5)。 | 
| TOKEN | FALSE | FALSE | FALSE |  永久金鑰，會跨叢集中的所有 HSM 進行複寫並包含在備份中。TOKEN = FALSE 代表一個暫時性金鑰，該金鑰會在與 HSM 的連接中斷時自動擦除。  | 
| UNWRAP | TRUE |  | TRUE | True 表示您可以使用金鑰來取消包裝 (匯入) 另一個金鑰。 | 
| VERIFY | TRUE | TRUE |  | True 表示您可以使用金鑰來驗證簽章。對於私有金鑰，這通常被設定為 FALSE。 | 
| WRAP | TRUE | TRUE |  | True 表示您可以使用該金鑰來包裝另一個金鑰。對於私有金鑰，您通常將此設定為 FALSE。 | 
| WRAP\$1WITH\$1TRUSTED | FALSE |  | FALSE | True 表示金鑰只能與 TRUSTED 屬性為 True 的金鑰進行包裝和取消包裝。一旦 金錀 WRAP\$1WITH\$1TRUSTED 設置為 True，該屬性僅為只讀狀態，不能將其設置為 False。如要了解有關信任包裝的資訊，請參閱[使用受信任金鑰控制金鑰解除包裝](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_using_trusted_keys_control_key_wrap.html)。 | 

**注意**  
您可以在 PKCS \$111 程式庫中獲得更廣泛的屬性支援。如需詳細資訊，請參閱[支援的 PKCS \$111 屬性](pkcs11-attributes.md)。

## 設定金鑰的屬性
<a name="java-setting-attributes_5"></a>

`KeyAttributesMap` 是類似 Java 映射的物件，您可以使用它來設定金鑰物件的屬性值。`KeyAttributesMap` 函數的方法類似於用於 Java 映射處理的方法。

若要設定屬性的自訂值，您有兩個選項：
+ 使用下表中列出的方法
+ 使用本文稍後示範的產生器模式

屬性映射物件支援以下列方法設定屬性：


****  

| 作業 | 傳回值 | `KeyAttributesMap` 方法 | 
| --- | --- | --- | 
| 獲取現有金鑰的金鑰屬性的值 | 物件 (包含值) 或 null |  **get**(keyAttribute)  | 
| 填入一個金鑰屬性的值  | 與金鑰屬性相關聯的先前值，如果金鑰屬性沒有映射，則為 null |  **put**(keyAttribute, value)  | 
| 填入多個金鑰屬性的值 | N/A |  **putAll**(keyAttributesMap)  | 
| 從屬性映射中刪除金鑰值對 |  與金鑰屬性相關聯的先前值，如果金鑰屬性沒有映射，則為 *null*  |  **remove**(keyAttribute)  | 

**注意**  
您未明確指定的任何屬性都會設定為[支援的屬性](#java-attributes_5)中上表所列的預設值。

### 設定金鑰對的屬性
<a name="java-setting-attributes-key-pair"></a>

使用 Java 類別 `KeyPairAttributesMap` 來處理金鑰對的金鑰屬性。`KeyPairAttributesMap` 封裝了兩個 `KeyAttributesMap` 物件；一個用於公有金鑰，另一個用於私有金鑰。

若要分別為公有金鑰和私有金鑰設定個別屬性，您可以在該金鑰對應的 `KeyAttributes` 映射物件上使用 `put()` 方法。使用 `getPublic()` 方法來擷取公有金鑰的屬性映射，以及使用 `getPrivate()` 來擷取私有金鑰的屬性映射。使用 `putAll()` 與金鑰對屬性映射作為引數，填入公有金鑰和私有金鑰對的多個金鑰屬性值。