支援的 Java 金錀屬性

本主題介紹了客戶端 SDK 5 支持的 Java 關鍵屬性的信息。本主題說明如何使用 JCE 提供程序的專屬擴充功能來設定金鑰屬性。請在以下操作期間，使用此擴充功能來設定支援的金鑰屬性及其值：

• 金鑰產生

• 金鑰匯入

如需如何使用金錀屬性的範例，請參閱 Java AWS CloudHSM 軟體程式庫的程式碼範例。

了解屬性

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

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

支援的屬性

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

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

注意

您可以在 PKCS #11 程式庫中獲得更廣泛的屬性支援。如需詳細資訊，請參閱支援的 PKCS #11 屬性。

設定金鑰的屬性

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

若要設定屬性的自訂值，您有兩個選項：

• 使用下表中列出的方法

• 使用本文稍後示範的產生器模式

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

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

注意

您未明確指定的任何屬性都會設定為支援的屬性中上表所列的預設值。

設定金鑰對的屬性

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

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