本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS CloudHSM 客户端 SDK 的 JCE 提供商 5
AWS CloudHSM JCE 提供程序是基于 Java 加密扩展 (JCE) 提供程序框架构建的提供程序实现。您可通过 JCE，使用 Java 开发工具包 (JDK) 执行加密操作。在本指南中， AWS CloudHSM JCE 提供者有时被称为 JCE 提供者。使用 JCE 提供程序和 JDK 将加密操作分流至 HSM。有关故障排除，请参阅[适用于 JCE 开发工具包的已知问题 AWS CloudHSM](ki-jce-sdk.md)。
有关使用客户端软件开发工具包 3 的信息，请参阅 [使用之前的 SDK 版本来使用 AWS CloudHSM](choose-client-sdk.md)。
**Topics**
+ [为 AWS CloudHSM 客户端 SDK 5 安装 JCE 提供程序](java-library-install_5.md)
+ [AWS CloudHSM 客户端 SDK 5 的 JCE 提供程序支持的密钥类型](java-lib-keys_5.md)
+ [AWS CloudHSM 客户端 SDK 5 的 JCE 提供程序中的密钥管理基础知识](java-library-key-basics_5.md)
+ [AWS CloudHSM 客户端 SDK 5 的 JCE 提供程序支持的机制](java-lib-supported_5.md)
+ [AWS CloudHSM 客户端 SDK 5 支持的 Java 密钥属性](java-lib-attributes_5.md)
+ [适用于客户端 SDK 5 的 Java AWS CloudHSM 软件库的代码示例](java-samples.md)
+ [AWS CloudHSM JCE 提供商 Javadocs](java-javadocs_5.md)
+ [AWS CloudHSM KeyStore 适用于客户端 SDK 5 的 Java 类](alternative-keystore_5.md)
+ [适用于客户端 SDK 5 的 AWS CloudHSM JCE 高级配置](java-lib-configs.md)
# 为 AWS CloudHSM 客户端 SDK 5 安装 JCE 提供程序
AWS CloudHSM 客户端 SDK 5 的 JCE 提供程序与 OpenJDK 8、OpenJDK 11、OpenJDK 17、OpenJDK 21 和 OpenJDK 25 兼容。您可以从 [OpenJDK 网站](https://openjdk.java.net/)下载两者。
使用以下部分来安装提供程序并向提供程序提供凭证。
**注意**
要使用客户端软件开发工具包 5 运行单个 HSM 集群，必须首先通过将 `disable_key_availability_check` 设置为 `True`，以管理客户端密钥持久性设置。有关更多信息，请参阅[密钥同步](manage-key-sync.md)和[客户端软件开发工具包 5 配置工具](configure-sdk-5.md)。
**Topics**
+ [步骤 1：安装 JCE 提供程序](#install-java-library_5)
+ [步骤 2：向 JCE 提供程序提供凭证](#java-library-credentials_5)
## 步骤 1：安装 JCE 提供程序
1. 使用以下命令下载和安装 JCE 提供程序。
------
#### [ Amazon Linux 2023 ]
在 x86\$164 架构上安装适用于 Amazon Linux 2023 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
在 ARM64 架构上安装适用于亚马逊 Linux 2023 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
在 x86\$164 架构上安装适用于 Amazon Linux 2 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm
```
在 ARM64 架构上安装适用于 Amazon Linux 2 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
在 x86\$164 架构上安装 RHEL 10 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.x86_64.rpm
```
在架构上安装 RHEL 10 的 JCE 提供程序： ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
在 x86\$164 架构上安装适用于 RHEL 9（9.2\$1）的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.x86_64.rpm
```
在架构上安装 RHEL 9 (9.2\$1) 的 JCE 提供程序： ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
在 x86\$164 架构上安装适用于 RHEL 8 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.x86_64.rpm
```
在架构上安装 RHEL 8 的 JCE 提供程序： ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
在 x86\$164 架构上安装适用于 Ubuntu 24.04 LTS 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_amd64.deb
```
在架构上安装 Ubuntu 24.04 LTS 的 JCE 提供程序： ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
在 x86\$164 架构上安装适用于 Ubuntu 22.04 LTS 的 JCE 提供程序：
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_amd64.deb
```
在架构上安装 Ubuntu 22.04 LTS 的 JCE 提供程序： ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
在 x86\$164 架构上安装适用于 Windows 服务器的 JCE 提供程序，以管理员 PowerShell 身份打开并运行以下命令：
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMJCE-latest.msi -Outfile C:\AWSCloudHSMJCE-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMJCE-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
------
1. 引导客户端软件开发工具包 5。有关引导程序的更多信息，请参阅 [引导客户端软件开发工具包](cluster-connect.md#connect-how-to)。
1. 找到以下 JCE 提供程序文件：
------
#### [ Linux ]
+ `/opt/cloudhsm/java/cloudhsm-.jar`
+ `/opt/cloudhsm/bin/configure-jce`
+ `/opt/cloudhsm/bin/jce-info`
------
#### [ Windows ]
+ `C:\Program Files\Amazon\CloudHSM\java\cloudhsm-.jar>`
+ `C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe`
+ `C:\Program Files\Amazon\CloudHSM\bin\jce_info.exe`
------
## 步骤 2：向 JCE 提供程序提供凭证
在您的 Java 应用程序可以使用 HSM 之前，HSM 需要先对应用程序进行身份验证。 HSMs 使用显式登录或隐式登录方法进行身份验证。
**显式登录**：此方法可让您直接在应用程序中提供 AWS CloudHSM 凭证。它使用 [https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html](https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html) 中的方法，以 PIN 模式传入 CU 用户名和密码。有关更多信息，请参阅[登录 HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java) 代码示例。
**隐式登录**：此方法可让您在新属性文件或系统属性中设置 AWS CloudHSM 凭证，或将该凭证设置为环境变量。
+ **系统属性**：在运行应用程序时通过系统属性设置凭证。以下示例演示了可执行此操作的两种不同方式：
------
#### [ Linux ]
```
$ java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
#### [ Windows ]
```
PS C:\> java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
+ **环境变量**：将凭证设置为环境变量。
**注意**
设置环境变量时，必须对外壳程序可能解释的任何特殊字符进行转义。
------
#### [ Linux ]
```
$ export HSM_USER=
$ export HSM_PASSWORD=
```
------
#### [ Windows ]
```
PS C:\> $Env:HSM_USER=""
PS C:\> $Env:HSM_PASSWORD=""
```
------
如果应用程序未提供凭证，或者在 HSM 验证会话前尝试执行操作，则凭证可能不可用。在这些情况下，适用于 Java 的 CloudHSM 软件库按以下顺序搜索凭证：
1. 系统属性
1. 环境变量
# AWS CloudHSM 客户端 SDK 5 的 JCE 提供程序支持的密钥类型
Java AWS CloudHSM 软件库允许您生成以下密钥类型。
****
| 密钥类型 | 说明 |
| --- | --- |
| AES | 生成 128 位、192 位和 256 位 AES 密钥。 |
| 三重 DES (3DES, DESede) | 生成一个 192 位的三重 DES 密钥。[*](#java-lib-keys_5-note-1) |
| EC | 生成 EC 密钥对：NIST 曲线 secp224r1 (P-224)、secp256r1 (P-256)、secp256k1 (区块链)、secp384r1 (P-384) 和 secp521r1 (P-521)。 |
| GENERIC\$1SECRET | 生成 1 至 800 字节的通用密钥。 |
| HMAC | 对 SHA1、、、 SHA224 SHA256 SHA384、的哈希支持 SHA512。 |
| RSA | 生成 2048 位到 4096 位的 RSA 密钥，增量为 256 位。 |
\$1 根据 NIST 指导，2023 年以后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群，2023 年之后仍然允许。有关详细信息，请参阅[FIPS 140 合规：2024 年机制弃用](compliance-dep-notif.md#compliance-dep-notif-1)。
# AWS CloudHSM 客户端 SDK 5 的 JCE 提供程序中的密钥管理基础知识
JCE 提供程序中密钥管理的基础知识涉及导入密钥、导出密钥、通过句柄加载密钥或删除密钥。有关管理密钥的更多信息，请参阅[管理密钥](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)代码示例。
另外，您可以在 [代码示例](java-samples.md) 中找到更多 JCE 提供程序代码示例。
# AWS CloudHSM 客户端 SDK 5 的 JCE 提供程序支持的机制
本主题提供有关 AWS CloudHSM 客户端 SDK 5 支持的 JCE 提供程序的机制的信息。有关支持的 Java 密码学架构 (JCA) 接口和引擎类的信息 AWS CloudHSM，请参阅以下主题。
**Topics**
+ [生成密钥与密钥对功能](#java-gen-key-pairs-5)
+ [密码函数](#java-ciphers_5)
+ [签署并验证功能](#java-sign-verify_5)
+ [摘要功能](#java-digests_5)
+ [HMAC 散列消息认证码函数](#java-mac_5)
+ [基于密码的消息身份验证码 (CMAC) 函数](#java-cmac_5)
+ [密钥协议函数](#java-key-derivation_5)
+ [使用密钥工厂将密钥转换为密钥规格](#java-key-factories)
+ [机制注释](#w2aac25c21c25c15c23)
## 生成密钥与密钥对功能
Java AWS CloudHSM 软件库允许您使用以下操作生成密钥和密钥对函数。
+ `RSA`
+ `EC`
+ `AES`
+ `DESede (Triple DES)`请参阅备注[1](#java-gen-key-pairs-5-note-1)
+ `GenericSecret`
## 密码函数
Java AWS CloudHSM 软件库支持以下算法、模式和填充组合。
| 算法 | Mode | Padding | 注意 |
| --- | --- | --- | --- |
| AES | CBC | `AES/CBC/NoPadding` `AES/CBC/PKCS5Padding` | 实施 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 实施 `Cipher.UNWRAP_MODE for AES/CBC NoPadding` |
| AES | ECB | `AES/ECB/PKCS5Padding` `AES/ECB/NoPadding` | 实施 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| AES | CTR | `AES/CTR/NoPadding` | 实施 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| AES | GCM | `AES/GCM/NoPadding` | 实施 `Cipher.WRAP_MODE`、`Cipher.UNWRAP_MODE`、`Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。执行 AES-GCM 加密时，HSM 会忽略请求中的初始化向量 (IV) 并使用其生成的 IV。当该操作完成时，您必须调用 `Cipher.getIV()` 以获取 IV。 |
| AESWrap | ECB | `AESWrap/ECB/NoPadding` `AESWrap/ECB/PKCS5Padding` `AESWrap/ECB/ZeroPadding` | 实施 `Cipher.WRAP_MODE` 和 `Cipher.UNWRAP_MODE`。 |
| DESede （三重 DES） | CBC | `DESede/CBC/PKCS5Padding` `DESede/CBC/NoPadding` | 实施 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。有关即将发生的更改，请参阅下面的注释 [1](#java-gen-key-pairs-5-note-1)。 |
| DESede （三重 DES） | ECB | `DESede/ECB/NoPadding` `DESede/ECB/PKCS5Padding` | 实施 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。有关即将发生的更改，请参阅下面的注释 [1](#java-gen-key-pairs-5-note-1)。 |
| RSA | ECB | `RSA/ECB/PKCS1Padding` **请参阅备注 [1](#java-gen-key-pairs-5-note-1)** `RSA/ECB/OAEPPadding` `RSA/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-512ANDMGF1Padding` | 实施 `Cipher.WRAP_MODE`、`Cipher.UNWRAP_MODE`、`Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| RSA | ECB | `RSA/ECB/NoPadding` | 实施 `Cipher.ENCRYPT_MODE` 和 `Cipher.DECRYPT_MODE`。 |
| RSAAESWrap | ECB | `RSAAESWrap/ECB/OAEPPadding` `RSAAESWrap/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-512ANDMGF1Padding` | 实施 `Cipher.WRAP_MODE` 和 `Cipher.UNWRAP_MODE`。 |
## 签署并验证功能
Java AWS CloudHSM 软件库支持以下类型的签名和验证。使用客户端软件开发工具包 5 和带哈希功能的签名算法，在数据发送至 HSM 进行签名/验证之前，会在软件中对数据进行本地哈希处理。这意味着可由 SDK 执行哈希处理的数据大小没有限制。
**RSA 签名类型**
+ `NONEwithRSA`
+ `RSASSA-PSS`
+ `SHA1withRSA`
+ `SHA1withRSA/PSS`
+ `SHA1withRSAandMGF1`
+ `SHA224withRSA`
+ `SHA224withRSAandMGF1`
+ `SHA224withRSA/PSS`
+ `SHA256withRSA`
+ `SHA256withRSAandMGF1`
+ `SHA256withRSA/PSS`
+ `SHA384withRSA`
+ `SHA384withRSAandMGF1`
+ `SHA384withRSA/PSS`
+ `SHA512withRSA`
+ `SHA512withRSAandMGF1`
+ `SHA512withRSA/PSS`
**ECDSA 签名类型**
+ `NONEwithECDSA`
+ `SHA1withECDSA`
+ `SHA224withECDSA`
+ `SHA256withECDSA`
+ `SHA384withECDSA`
+ `SHA512withECDSA`
## 摘要功能
Java AWS CloudHSM 软件库支持以下消息摘要。通过客户端软件开发工具包 5，数据将在软件中进行本地哈希处理。这意味着可由 SDK 执行哈希处理的数据大小没有限制。
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
## HMAC 散列消息认证码函数
Java AWS CloudHSM 软件库支持以下 HMAC 算法。
+ `HmacSHA1`（以字节为单位的最大数据大小：16288）
+ `HmacSHA224`（以字节为单位的最大数据大小：16256）
+ `HmacSHA256`（以字节为单位的最大数据大小：16288）
+ `HmacSHA384`（以字节为单位的最大数据大小：16224）
+ `HmacSHA512`（以字节为单位的最大数据大小：16224）
## 基于密码的消息身份验证码 (CMAC) 函数
CMACs （基于密码的消息身份验证码）使用分组密码和密钥创建消息身份验证码 (MACs)。它们的不同之处 HMACs 在于，它们使用区块对称密钥方法 MACs 而不是哈希方法。
适用于 Java 的 AWS CloudHSM 软件库支持以下 CMAC 算法。
+ `AESCMAC`
## 密钥协议函数
Java AWS CloudHSM 软件库支持带有密钥派生函数 (KDF) 的 ECDH。支持以下 KDF 类型：
+ `ECDHwithX963SHA1KDF`支持 X9.63 KDF 算法 SHA1 [2](#kdf2)
+ `ECDHwithX963SHA224KDF`支持 X9.63 KDF 算法 SHA224 [2](#kdf2)
+ `ECDHwithX963SHA256KDF`支持 X9.63 KDF 算法 SHA256 [2](#kdf2)
+ `ECDHwithX963SHA384KDF`支持 X9.63 KDF 算法 SHA384 [2](#kdf2)
+ `ECDHwithX963SHA512KDF`支持 X9.63 KDF 算法 SHA512 [2](#kdf2)
## 使用密钥工厂将密钥转换为密钥规格
您可以使用密钥工厂将密钥转换为密钥规格。 AWS CloudHSM JCE 有两种类型的关键工厂：
**SecretKeyFactory：**用于导入或派生对称密钥。使用 SecretKeyFactory，您可以传递支持的密钥或支持的密钥 KeySpec 以导入或派生对称密钥。 AWS CloudHSM以下是支持的规格 KeyFactory：
+ F SecretKeyFactory o `generateSecret` r 的方法支持以下[KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)类：
+ **KeyAttributesMap**可用于将带有附加属性的密钥字节作为 CloudHSM 密钥导入。可以在[此处](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)找到一个示例。
+ **[SecretKeySpec](https://docs.oracle.com/javase/8/docs/api/javax/crypto/spec/SecretKeySpec.html)**可用于将对称密钥规范作为 CloudHSM 密钥导入。
+ **AesCmacKdfParameterSpec**可用于使用另一个 CloudHSM AES 密钥派生对称密钥。
**注意**
SecretKeyFactory的`translateKey`方法接受任何实现密钥接口的[密钥](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html)。
**KeyFactory：**用于导入非对称密钥。使用 KeyFactory，您可以传递支持的密钥或支持的密钥 KeySpec 以将非对称密钥导入其中 AWS CloudHSM。更多信息，请参阅以下资源：
+ KeyFactory对于`generatePublic`的方法，支持以下[KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)类：
+ 适用于 RSA 和 EC 的 KeyAttributesMap CloudHSM，包括： KeyTypes
+ Cloud KeyAttributesMap HSM 适用于 RSA 和 EC 公众。 KeyTypes可以在[此处](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)找到示例。
+ [X509](https://docs.oracle.com/javase/8/docs/api/java/security/spec/X509EncodedKeySpec.html) 同时EncodedKeySpec适用于 RSA 和 EC 公钥
+ [RSAPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPublicKeySpec.html)适用于 RSA 公钥
+ [ECPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPublicKeySpec.html)适用于 EC 公钥
+ KeyFactory对于`generatePrivate`的方法，支持以下[KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)类：
+ 适用于 RSA 和 EC 的 KeyAttributesMap CloudHSM，包括： KeyTypes
+ Cloud KeyAttributesMap HSM 适用于 RSA 和 EC 公众。 KeyTypes可以在[此处](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)找到示例。
+ [PKCS8EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/PKCS8EncodedKeySpec.html)适用于 EC 和 RSA 私钥
+ [RSAPrivateCrtKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPrivateCrtKeySpec.html)适用于 RSA 私钥
+ [ECPrivateKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPrivateKeySpec.html)适用于 EC 私钥
对于 KeyFactory的`translateKey`方法来说，它接受任何实现密钥[接口的密钥](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html)。
## 机制注释
[1] 根据 NIST 指导，2023 年以后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群，2023 年之后仍然允许。有关详细信息，请参阅 [FIPS 140 合规：2024 年机制弃用](compliance-dep-notif.md#compliance-dep-notif-1)。
[2] [NIST 特别出版物 800-56A 修订版 3 中规定了密钥派](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf)生函数 (KDFs)。
# AWS CloudHSM 客户端 SDK 5 支持的 Java 密钥属性
本主题提供有关 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)
## 了解属性
可以使用密钥属性指定允许对密钥对象（包括公有密钥或私有密钥）执行哪些操作。可以在创建密钥对象的过程中定义密钥属性和值。
Java Cryptography Extension (JCE) 不指定如何设置密钥属性值，因此，默认情况下允许执行大多数操作。相比之下，PKCS \$111 标准定义了一组具有更受限的默认值的综合属性。从 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\$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)。
## 设置密钥的属性
`KeyAttributesMap` 是一个类似于 Java Map 的对象，可以使用它设置密钥对象的属性值。`KeyAttributesMap` 函数的方法与用于 Java 映射操作的方法类似。
可以通过下面两种方式为属性设置自定义值：
+ 使用下表中列出的方法
+ 使用本文档后面演示的生成器模式
属性映射对象支持通过以下方法来设置属性：
****
| 操作 | 返回值 | `KeyAttributesMap` 方法 |
| --- | --- | --- |
| 获取现有密钥的密钥属性值 | 对象（包含值）或 null | **get**(keyAttribute) |
| 填充一个密钥属性的值 | 与密钥属性关联的上一个值，或 null（如果没有密钥属性的映射） | **put**(keyAttribute, value) |
| 填充多个密钥属性的值 | 不适用 | **putall** () keyAttributesMap |
| 从属性映射中删除密钥/值对 | 与密钥属性关联的上一个值，或 *null*（如果没有密钥属性的映射） | **remove**(keyAttribute) |
**注意**
未明确指定的任何属性都将设置为 [支持的 属性](#java-attributes_5) 中前面的表中列出的默认值。
### 设置密钥对的属性
使用 Java 类 `KeyPairAttributesMap` 处理密钥对的密钥属性。`KeyPairAttributesMap` 封装了两个 `KeyAttributesMap` 对象；一个用于公有密钥，另一个用于私有密钥。
要分别为公有密钥和私有密钥设置单个属性，您可以对该密钥的相应 `KeyAttributes` 映射对象使用 `put()` 方法。使用 `getPublic()` 方法可检索公有密钥的属性映射，使用 `getPrivate()` 可检索私有密钥的属性映射。使用 `putAll()` 填充公有密钥和私有密钥对的多个密钥属性的值，并将密钥对属性映射作为其参数。
# 适用于客户端 SDK 5 的 Java AWS CloudHSM 软件库的代码示例
本主题提供有关 AWS CloudHSM Client SDK 5 的 Java 代码示例的资源和信息。
## 先决条件
运行示例前，必须设置环境：
+ 安装和配置 [Java 加密扩展（JCE）提供程序](java-library-install_5.md#install-java-library_5)。
+ 设置有效的 [HSM 用户名和密码](manage-hsm-users.md)。加密用户 (CU) 权限足以执行这些任务。在每个示例中，您的应用程序都将使用这些凭证登录 HSM。
+ 决定如何向 [JCE 提供程序](java-library-install_5.md#java-library-credentials_5) 提供凭证。
## 代码示例
以下代码示例向您展示了如何使用 [AWS CloudHSM JCE 提供程序](java-library.md) 执行基本任务。有关更多代码示例，请访问[GitHub](https://github.com/aws-samples/aws-cloudhsm-jce-examples/tree/sdk5)。
+ [登录 HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)
+ [管理密钥](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [生成对称密钥](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)
+ [生成非对称密钥](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java)
+ [使用 AES-GCM 加密和解密](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java)
+ [使用 AES-CTR 加密和解密](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java)
+ 使用@@ [ DESede-ECB 加密和解密参见备注](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java) [1](#java-samples-code-5-note-1)
+ [使用 RSA 密钥签名和验证](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/RSAOperationsRunner.java)
+ [使用 EC 密钥签名和验证](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.java)
+ [使用支持的关键属性](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyAttributesRunner.java)
+ [使用 CloudHSM 密钥存储](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.java)
[1] 根据 NIST 指导，2023 年以后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群，2023 年之后仍然允许。有关详细信息，请参阅[FIPS 140 合规：2024 年机制弃用](compliance-dep-notif.md#compliance-dep-notif-1)。
# AWS CloudHSM JCE 提供商 Javadocs
使用 JCE 提供程序 Javadocs 获取有关 AWS CloudHSM JCE SDK 中定义的 Java 类型和方法的使用信息。要下载最新的 Javadocs AWS CloudHSM，请参阅 “下载[AWS CloudHSM 最新客户端 SDK 版本](latest-releases.md)” 页面上的部分。
您可以将 Javadocs 导入集成式开发环境（IDE）或在 Web 浏览器中查看它们。
# AWS CloudHSM KeyStore 适用于客户端 SDK 5 的 Java 类
该 AWS CloudHSM `KeyStore`类提供特殊用途的 PKCS12 密钥存储库。该密钥库可以将证书与您的密钥数据一起存储，并将它们与存储在 AWS CloudHSM上的密钥数据相关联。该 AWS CloudHSM `KeyStore`类实现了 Java 密码学扩展 (JCE) 的`KeyStore`服务提供者接口 (SPI)。有关使用的更多信息`KeyStore`，请参阅[类KeyStore](https://devdocs.io/openjdk~8/java/security/keystore)。
**注意**
由于证书是公共信息，并且为了最大限度地提高加密密钥的存储容量，因此 AWS CloudHSM 不支持在上 HSMs存储证书。
## 为 AWS CloudHSM 客户端 SDK 5 选择合适的密钥库
AWS CloudHSM Java 加密扩展 (JCE) 提供商提供特殊用途的 AWS CloudHSM。 KeyStore该 AWS CloudHSM `KeyStore`类支持将密钥操作卸载到 HSM、证书的本地存储和基于证书的操作。
按如下方式加载特殊用途 KeyStore CloudHSM：
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## 初始化 AWS CloudHSM KeyStore 客户端 SDK 5
使用与登录 JCE 提供程序相同的方式登录。 AWS CloudHSM KeyStore 您可以使用环境变量或系统属性文件，并且应该在开始使用 CloudHSM KeyStore 之前登录。有关使用 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 对象 KeyStore ：
```
ks.load(null, null);
```
使用 `store` 方法将密钥库数据写入文件。从那时起，您可以使用带有源文件和密码的 `load` 方法加载现有密钥库，如下所示：
```
ks.load(inputStream, password);
```
## 使用我们的 AWS CloudHSM KeyStore AWS CloudHSM 客户端 SDK 5
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 entry = ks.aliases(); entry.hasMoreElements();) {
String label = entry.nextElement();
System.out.println(label);
}
```
+ `containsalias`
如果密钥库可以访问至少一个具有指定别名的对象，则返回 true。密钥库检查存储在 PKCS12 文件中的本地对象和驻留在 HSM 上的对象。
+ `deleteEntry`
从本地 PKCS12 文件中删除证书条目。不支持使用删除存储在 HSM 中的密钥数据。 AWS CloudHSM KeyStore您可以使用 [Destroyable](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 上的任何密钥，无论该密钥是否由生成。 KeyStore
```
Key key = ks.getKey(keyLabel, null);
```
+ `isCertificateEntry`
检查具有给定别名的条目是否表示证书条目。
+ `isKeyEntry`
检查具有给定别名的条目是否表示密钥条目。该操作在 PKCS12 文件和 HSM 中搜索别名。
+ `setCertificateEntry`
将给定证书分配给给定别名。如果给定的别名已被用于标识密钥或证书，则会引发 `KeyStoreException`。您可以使用 JCE 代码获取密钥对象，然后使用 KeyStore `SetKeyEntry`方法将证书与密钥相关联。
+ 使用 `byte[]` 密钥执行 `setKeyEntry`
**客户端软件开发工具包 5 目前不支持此 API。**
+ 使用 `Key` 对象执行 `setKeyEntry`
将给定密钥分配到给定别名并将其存储在 HSM 中。如果 HSM 中尚不存在该密钥，则会将其作为可提取的会话密钥导入 HSM。
如果 `Key` 对象属于类型 `PrivateKey`，则它必须伴随相应的证书链。
如果别名已存在，则 `SetKeyEntry` 调用会引发 `KeyStoreException`，并阻止该密钥被覆盖。如果密钥必须被覆盖，请为此目的使用 KMU 或 JCE。
+ `engineSize`
返回密钥库中的条目数。
+ `store`
将密钥存储库作为 PKCS12 文件存储到给定输出流，并使用给定的密码对其进行保护。此外，它会保留所有加载的密钥（使用 `setKey` 调用进行设置）。
# 适用于客户端 SDK 5 的 AWS CloudHSM JCE 高级配置
AWS CloudHSM JCE 提供商包括以下高级配置，这些配置不是大多数客户使用的常规配置的一部分。
+ [连接到多个集群](java-lib-configs-multi.md)
+ [使用 JCE 提取密钥](java-lib-configs-getencoded.md)
+ [JCE 重试配置](java-lib-configs-retry.md)
# 使用 JCE 提供程序连接到多个 AWS CloudHSM 集群
此配置允许单个客户端实例与多个 AWS CloudHSM 集群通信。对于某些用例来说，与让单个实例仅与单个集群通信相比，这可能是项节省成本的功能。该`CloudHsmProvider`类是 [Java AWS CloudHSM Security 的 Provider 类的](https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html)实现。此类的每个实例都代表与整个 AWS CloudHSM 集群的连接。您可以实例化该类并将其添加到 Java Security 提供程序的列表中，以便您可以使用标准 JCE 类与之交互。
以下示例实例化该类并将其添加到 Java Security 提供程序的列表中：
```
if (Security.getProvider(CloudHsmProvider.PROVIDER_NAME) == null) {
Security.addProvider(new CloudHsmProvider());
}
```
`CloudHsmProvider` 可以通过下列两种方式进行配置：
1. 使用文件进行配置（默认配置）
1. 使用代码进行配置
以下主题介绍了这些配置以及如何连接到多个集群。
**Topics**
+ [使用文件配置 AWS CloudHSM `CloudHsmProvider` 类（默认配置）](java-lib-configs-default.md)
+ [使用代码配置 AWS CloudHSM `CloudHsmProvider` 类](java-lib-configs-using-code.md)
+ [Connect 连接到多个 AWS CloudHSM 集群](java-lib-connecting-to-multiclusters.md)
# 使用文件配置 AWS CloudHSM `CloudHsmProvider` 类（默认配置）
配置 AWS CloudHSM `CloudHsmProvider`类的默认方法是使用文件。
当您使用默认构造函数实例化 `CloudHsmProvider` 时，默认情况下，它会在 Linux 的 `/opt/cloudhsm/etc/cloudhsm-jce.cfg` 路径中查找配置文件。该配置文件可使用 `configure-jce` 进行配置。
使用默认构造函数创建的对象将使用默认 CloudHSM 提供程序名称 `CloudHSM`。提供程序的名称对于与 JCE 交互非常有用，可以让 JCE 知道要使用哪个提供程序进行各类操作。使用 CloudHSM 提供程序名称进行密码操作的示例如下所示：
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHSM");
```
# 使用代码配置 AWS CloudHSM `CloudHsmProvider` 类
从客户端 SDK 版本 5.8.0 开始，您还可以使用 Java 代码配置该 AWS CloudHSM `CloudHsmProvider`类。做到这一点的方法是使用 `CloudHsmProviderConfig` 类的对象。您可以使用 `CloudHsmProviderConfigBuilder` 构建此对象。
`CloudHsmProvider` 还有另一个接受 `CloudHsmProviderConfig` 对象的构造函数，如以下示例所示。
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider = new CloudHsmProvider(config);
```
在此示例中，JCE 提供程序的名称为 `CloudHsmCluster1`。这是应用程序随后可用于与 JCE 交互的名称：
**Example**
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHsmCluster1");
```
或者应用程序也可以使用上面创建的提供程序对象让 JCE 知道要使用该提供程序进行操作：
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider);
```
如果未在 `withClusterUniqueIdentifier` 方法中指定唯一标识符，则会为您创建一个随机生成的提供程序名称。要获取这个随机生成的标识符，应用程序可以调用 `provider.getName()` 获取该标识符。
# Connect 连接到多个 AWS CloudHSM 集群
每个都`CloudHsmProvider`代表与您的集 AWS CloudHSM 群的连接。如果您想与来自同一应用程序的另一个集群通信，则可以使用另一个集群的配置创建另一个 `CloudHsmProvider` 对象，也可以使用提供程序对象或提供程序名称与另一个集群进行交互，如以下示例所示。
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider1 = new CloudHsmProvider(config);
if (Security.getProvider(provider1.getName()) == null) {
Security.addProvider(provider1);
}
CloudHsmProviderConfig config2 = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath2)
.withClusterUniqueIdentifier("CloudHsmCluster2")
.withServer(CloudHsmServer.builder().withHostIP(hostName2).build())
.build())
.build();
CloudHsmProvider provider2 = new CloudHsmProvider(config2);
if (Security.getProvider(provider2.getName()) == null) {
Security.addProvider(provider2);
}
```
配置了上面的两个提供程序（均为集群）后，就可以使用提供程序对象或提供程序名称与它们进行交互。
在此演示如何与之交谈的示例的基础上`cluster1`，您可以使用以下示例进行AES/GCM/NoPadding操作：
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider1);
```
在同一个应用程序中，要使用提供程序名称在第二个集群上生成“AES”密钥，也可以使用以下示例：
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider2.getName());
```
# 使用 JCE 提取密钥 AWS CloudHSM
Java 密码学扩展 (JCE) 使用的架构允许插入不同的加密实现。 AWS CloudHSM 发布了一个这样的 JCE 提供商，它可以将加密操作卸载到 HSM。对于大多数其他 JCE 提供商来说，要使用存储在 AWS CloudHSM 中的密钥，他们必须将您的密钥字节以明文形式提取 HSMs 到您的计算机内存中供他们使用。 HSMs 通常只允许将密钥提取为封装对象，而不允许以明文形式提取。但是，为了支持提供商间集成用例， AWS CloudHSM 允许使用选择加入配置选项来启用密钥字节的提取。
**重要**
AWS CloudHSM 无论何时指定 AWS CloudHSM 提供程序或 AWS CloudHSM 使用密钥对象，JCE 都会将操作卸载到任何时候。如果您希望在 HSM 内部进行操作，则无需以明文方式提取密钥。只有当您的应用程序由于第三方库或 JCE 提供程序的限制而无法使用安全机制（例如包装和解包密钥）时，才需要以明文提取密钥。
默认情况下， AWS CloudHSM JCE 提供程序允许提取**公钥**，以便与外部 JCE 提供程序配合使用。始终允许使用以下方法：
| 类 | 方法 | 格式 (getEncoded) |
| --- | --- | --- |
| EcPublicKey | getEncoded() | X.509 |
| | getW() | 不适用 |
| RSAPublic钥匙 | getEncoded() | X.509 |
| | getPublicExponent() | 不适用 |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | 不适用 |
默认情况下， AWS CloudHSM JCE 提供程序不允许提取私钥或**私**钥的**密**钥字节。如果您的用例需要，则可以在以下条件下启用**私有**密钥或**机密**密钥的明文密钥字节提取功能：
1. 私有密钥和机密密钥的 `EXTRACTABLE` 属性设置为 **true**。
+ 默认情况下，私有密钥和机密密钥的 `EXTRACTABLE` 属性设置为 **true**。`EXTRACTABLE` 密钥是允许从 HSM 中导出的密钥。有关更多信息，请参阅《[客户端软件开发工具包 5](java-lib-attributes_5.md) 支持的 Java 属性》。
1. 私有密钥和机密密钥的 `WRAP_WITH_TRUSTED` 属性设置为 **false**。
+ `getEncoded`、`getPrivateExponent` 和 `getS` 不能与无法以明文导出的私有密钥一起使用。`WRAP_WITH_TRUSTED` 不允许您的私有密钥以明文从 HSM 中导出。有关更多信息，请参阅[使用可信密钥控制密钥解包](manage-keys-using-trusted-keys.md)。
# 允许 JCE 提供者从中提取私钥机密 AWS CloudHSM
使用以下步骤允许 AWS CloudHSM JCE 提供者提取您的私钥机密。
**重要**
此配置更改允许从 HSM 集群中以明文提取所有 `EXTRACTABLE` 密钥字节。为了提高安全性，您应该考虑使用[密钥包装方法](java-lib-supported_5.md)将密钥安全地从 HSM 中提取出来。这样可以防止无意中从 HSM 中提取密钥字节。
1. 使用以下命令从 JCE 中提取您的**私有**密钥或**机密**密钥：
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --enable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --enable-clear-key-extraction-in-software
```
------
1. 一旦启用了明文密钥提取功能，就会启用以下方法将私有密钥提取到内存中。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/get-encoded-take-out-private-keys.html)
如果要恢复默认行为并且不允许 JCE 以明文导出密钥，请运行以下命令：
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --disable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-clear-key-extraction-in-software
```
------
# 用于 JCE 的重试命令 AWS CloudHSM
AWS CloudHSM 客户端 SDK 5.8.0 及更高版本具有内置的自动重试策略，该策略将从客户端重试 HSM 限制的操作。当 HSM 因忙于执行之前的操作而无法接受更多请求而限制操作时，客户端 SDKs 将尝试重试受限制的操作最多 3 次，同时呈指数级退缩。这种自动重试策略可设置为以下两种模式之一：**关闭**和**标准**。
+ **关闭**：客户端软件开发工具包 不会对 HSM 的任何节流操作执行任何重试策略。
+ **标准**：这是客户端软件开发工具包版本 5.8.0 及更高版本的默认模式。在此模式下，客户端 SDKs 将通过指数级退出自动重试受限制的操作。
有关更多信息，请参阅 [HSM 节流](troubleshoot-hsm-throttling.md)。
## 将重试命令设置为关闭模式
------
#### [ Linux ]
**在 Linux 上将客户端软件开发工具包 5 的重试命令设置为 **off****
+ 您可以使用以下命令将重试配置设置为 **off** 模式：
```
$ sudo /opt/cloudhsm/bin/configure-jce --default-retry-mode off
```
------
#### [ Windows ]
**在 Windows 上将客户端软件开发工具包 5 的重试命令设置为 **off****
+ 您可以使用以下命令将重试配置设置为 **off** 模式：
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --default-retry-mode off
```
------