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

# AWS CloudHSM 客户端 SDK 5 支持的 Java 密钥属性
<a name="java-lib-attributes_5"></a>

本主题提供有关 AWS CloudHSM 客户端 SDK 5 支持的 Java 密钥属性的信息。本主题介绍了如何使用 JCE 提供程序的专有扩展来设置密钥属性。使用此扩展可在以下操作期间设置受支持的密钥属性及其值：
+ 密钥生成
+ 密钥导入

有关如何使用密钥属性的示例，请参阅 [适用于客户端 SDK 5 的 Java 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 表示用户在通过身份验证之前将无法访问密钥。为清楚起见，即使此属性设置为 FALSE，用户在通过身份验证 AWS CloudHSM 之前也无法访问任何密钥。 | 
| SIGN | TRUE |  | TRUE | True 表示可使用密钥对消息摘要进行签名。对于已存档的公有密钥和私有密钥，此项通常设置为 FALSE。 | 
| SIZE |  |  |  | 定义密钥大小的属性。有关支持的密钥大小的更多详细信息，请参阅[客户端开发工具包 5 支持的机制](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-lib-supported_5.html#java-keys_5)。 | 
| TOKEN | FALSE | FALSE | FALSE |  永久密钥，在集群 HSMs 中的所有密钥中复制并包含在备份中。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 Map 的对象，可以使用它设置密钥对象的属性值。`KeyAttributesMap` 函数的方法与用于 Java 映射操作的方法类似。

可以通过下面两种方式为属性设置自定义值：
+ 使用下表中列出的方法
+ 使用本文档后面演示的生成器模式

属性映射对象支持通过以下方法来设置属性：


****  

| 操作 | 返回值 | `KeyAttributesMap` 方法 | 
| --- | --- | --- | 
| 获取现有密钥的密钥属性值 | 对象（包含值）或 null |  **get**(keyAttribute)  | 
| 填充一个密钥属性的值  | 与密钥属性关联的上一个值，或 null（如果没有密钥属性的映射） |  **put**(keyAttribute, value)  | 
| 填充多个密钥属性的值 | 不适用 |  **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()` 填充公有密钥和私有密钥对的多个密钥属性的值，并将密钥对属性映射作为其参数。