# Using Client SDK 5 to work with AWS CloudHSM
AWS CloudHSM includes two major Client SDK versions:
+ Client SDK 5: This is our latest and default Client SDK. For information on the benefits and advantages it provides, see [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md).
+ Client SDK 3: This is our older Client SDK. It includes a full set of components for platform and language-based applications compatibility and management tools.
For instructions on migrating from Client SDK 3 to Client SDK 5, see [Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5](client-sdk-migration.md).
This topic describes Client SDK 5. To check what version of Client SDK you're using, see
**Topics**
+ [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md)
+ [AWS CloudHSM Client SDK 5 supported platforms](client-supported-platforms.md)
+ [PKCS \$111 library for AWS CloudHSM Client SDK 5](pkcs11-library.md)
+ [OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl-library.md)
+ [OpenSSL Provider for AWS CloudHSM Client SDK 5](openssl-provider-library.md)
+ [Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library.md)
+ [JCE provider for AWS CloudHSM Client SDK 5](java-library.md)
# Benefits of AWS CloudHSM Client SDK 5
Compared to AWS CloudHSM Client SDK 3, Client SDK 5 is easier to manage, offers superior configurability, and increased reliability. Client SDK 5 also provides some additional key advantages to Client SDK 3.
**Designed for serverless architecture**
Client SDK 5 does not require a client daemon, so you no longer need to manage a background service. This helps users in a few important ways:
+ Simplifies the application startup process. All you need to do to get started with CloudHSM is configure the SDK before running your application.
+ You don't need a constantly running process, which makes integration with serverless components like Lambda and Elastic Container Service (ECS) easier.
**Better third party integrations and easier portability**
Client SDK 5 follows the JCE specification closely and provides easier portability between different JCE providers and better third party integrations
**Improved user experience and configurability**
Client SDK 5 improves log message readability and provides clearer exceptions and error-handling mechanisms, all of which makes self-service triaging much easier for users. SDK 5 also offers a variety of configurations, which are listed in the [Configure Tool page](https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sdk-5.html).
**Broader platform support**
Client SDK 5 offers more support for modern operating platforms. This includes support for ARM technologies and greater support for [JCE](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-library_5.html), [PKCS\$111](https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library.html), and [OpenSSL](https://docs.aws.amazon.com/cloudhsm/latest/userguide/openssl-library.html). For more information, refer to [Supported platforms](client-supported-platforms.md).
**IPv6 connection support**
Client SDK 5.14\$1 supports connections to dual-stack HSMs using IPv6.
**Additional features and mechanisms**
Client SDK 5 includes additional features and mechanisms that are not available in Client SDK 3, and Client SDK 5 will continue to add more mechanisms in the future.
# AWS CloudHSM Client SDK 5 supported platforms
Base support is different for each version of the AWS CloudHSM Client SDK. Platform support for components in an SDK typically matches base support, but not always. To determine platform support for a given component, first make sure the platform you want appears in the base section for the SDK, then check for any exclusions or any other pertinent information in the component section.
AWS CloudHSM supports only 64-bit operating systems.
Platform support changes over time. Earlier versions of the CloudHSM Client SDK may not support all the operating systems listed here. Use release notes to determine the operating system support for previous versions of the CloudHSM Client SDK. For more information, see [Downloads for AWS CloudHSM Client SDK](client-history.md).
For supported platforms for the previous Client SDK, see [AWS CloudHSM Client SDK 3 supported platforms](sdk3-support.md)
Client SDK 5 does not require a client daemon.
**Topics**
+ [Linux support for Client SDK 5](sdk8-linux.md)
+ [Windows support for Client SDK 5](sdk8-windows.md)
+ [Serverless support for Client SDK 5](sdk8-serverless.md)
+ [HSM compatibility for Client SDK 5](sdk5-hsm-types.md)
# Linux support for AWS CloudHSM Client SDK 5
AWS CloudHSM Client SDK 5 supports the following Linux operating systems and platforms.
| Supported platforms | X86\$164 Architecture | ARM architecture |
| --- | --- | --- |
| Amazon Linux 2 | Yes | Yes |
| Amazon Linux 2023 | Yes | Yes |
| Red Hat Enterprise Linux 8 (8.3\$1) | Yes | Yes |
| Red Hat Enterprise Linux 9 (9.2\$1) | Yes | Yes |
| Red Hat Enterprise Linux 10 (10.0\$1) | Yes | Yes |
| Ubuntu 22.04 LTS | Yes | Yes |
| Ubuntu 24.04 LTS | Yes | Yes |
+ SDK 5.16 was the last release to provide Ubuntu 20.04 LTS platform support. For more information, see the [Ubuntu website](https://ubuntu.com/blog/ubuntu-20-04-lts-end-of-life-standard-support-is-coming-to-an-end-heres-how-to-prepare).
+ SDK 5.12 was the last release to provide CentOS 7 (7.8\$1) platform support. For more information, see the [CentOS website](https://blog.centos.org/2023/04/end-dates-are-coming-for-centos-stream-8-and-centos-linux-7/).
+ SDK 5.12 was the last release to provide Red Hat Enterprise Linux 7 (7.8\$1) platform support. For more information, see the [Red Hat website](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/rhel-7-end-of-maintenance).
+ SDK 5.4.2 was the last release to provide CentOS 8 platform support. For more information, see the [CentOS website](https://www.centos.org/centos-linux-eol/).
# Windows support for AWS CloudHSM Client SDK 5
AWS CloudHSM Client SDK 5 supports the following versions of Windows Server.
+ Microsoft Windows Server 2016
+ Microsoft Windows Server 2019
+ Microsoft Windows Server 2022
+ Microsoft Windows Server 2025
# Serverless support for AWS CloudHSM Client SDK 5
AWS CloudHSM Client SDK 5 supports the following AWS serverless services.
+ AWS Lambda
+ Docker/ECS
# HSM compatibility for AWS CloudHSM Client SDK 5
The following table describes AWS CloudHSM Client SDK 5 compatibility for HSMs.
| hsm1.medium | hsm2m.medium |
| --- | --- |
| Compatible with Client SDK version 5.0.0 and later. | Compatible with Client SDK version 5.9.0 and later. |
# PKCS \$111 library for AWS CloudHSM Client SDK 5
PKCS \$111 is a standard for performing cryptographic operations on hardware security modules (HSMs). AWS CloudHSM offers implementations of the PKCS \$111 library that are compliant with PKCS \$111 version 2.40.
For information about bootstrapping, see [Connecting to the cluster](cluster-connect.md). For troubleshooting, see [Known issues for the PKCS \$111 library for AWS CloudHSMKnown issues for the PKCS \$111 library](ki-pkcs11-sdk.md).
For information on using Client SDK 3, see [Using previous SDK version to work with AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Install the PKCS \$111 library](pkcs11-library-install.md)
+ [Authenticate to the PKCS \$111 library](pkcs11-pin.md)
+ [Key types](pkcs11-key-types.md)
+ [Mechanisms](pkcs11-mechanisms.md)
+ [API operations](pkcs11-apis.md)
+ [Key attributes](pkcs11-attributes.md)
+ [Code samples](pkcs11-samples.md)
+ [Advanced configurations](pkcs11-library-configs.md)
+ [Certificate storage](pkcs11-certificate-storage.md)
# Install the PKCS \$111 library for AWS CloudHSM Client SDK 5
This topic provides instructions for installing the latest version of the PKCS \$111 library for the AWS CloudHSM Client SDK 5 version series. For more information about the Client SDK or PKCS \$111 library, see [Using the Client SDK](use-hsm.md) and [PKCS \$111 library](pkcs11-library.md).
With Client SDK 5, you are not required to install or run a client daemon.
To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](manage-key-sync.md) and [Client SDK 5 Configure Tool](configure-sdk-5.md).
For more information about the PKCS \$111 library in Client SDK 5, see [PKCS \$111 library](pkcs11-library.md).
**Note**
To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](manage-key-sync.md) and [Client SDK 5 Configure Tool](configure-sdk-5.md).
**To install and configure the PKCS \$111 library**
1. Use the following commands to download and install the PKCS \$111 library.
------
#### [ Amazon Linux 2023 ]
Install the PKCS \$111 library for Amazon Linux 2023 on X86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
Install the PKCS \$111 library for Amazon Linux 2023 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
Install the PKCS \$111 library for Amazon Linux 2 on X86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
Install the PKCS \$111 library for Amazon Linux 2 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
Install the PKCS \$111 library for RHEL 10 on X86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
Install the PKCS \$111 library for RHEL 10 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Install the PKCS \$111 library for RHEL 9 on X86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
Install the PKCS \$111 library for RHEL 9 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
Install the PKCS \$111 library for RHEL 8 on X86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
Install the PKCS \$111 library for RHEL 8 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Install the PKCS \$111 library for Ubuntu 24.04 LTS on X86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
Install the PKCS \$111 library for Ubuntu 24.04 LTS on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Install the PKCS \$111 library for Ubuntu 22.04 LTS on X86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
Install the PKCS \$111 library for Ubuntu 22.04 LTS on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
Install the PKCS \$111 library for Windows Server on X86\$164 architecture:
1. Download [PKCS \$111 library for Client SDK 5](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMPKCS11-latest.msi).
1. Run the PKCS \$111 library installer (**AWSCloudHSMPKCS11-latest.msi**) with Windows administrative privilege.
------
1. Use the configure tool to specify the location of the issuing certificate. For instructions, see [Specify the location of the issuing certificate](cluster-connect.md#specify-cert-location).
1. To connect to your cluster, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. You can find the PKCS \$111 library files in the following locations:
+ Linux binaries, configuration scripts, and log files:
```
/opt/cloudhsm
```
Windows binaries:
```
C:\Program Files\Amazon\CloudHSM
```
Windows configuration scripts and log files:
```
C:\ProgramData\Amazon\CloudHSM
```
# Authenticate to the PKCS \$111 library for AWS CloudHSM Client SDK 5
When you use the PKCS \$111 library, your application runs as a particular [crypto user (CU)](manage-hsm-users.md) in your HSMs in AWS CloudHSM. Your application can view and manage only the keys that the CU owns and shares. You can use an existing CU in your HSMs or create a new CU for your application. For information on managing CUs, see [Managing HSM users with CloudHSM CLI](manage-hsm-users-chsm-cli.md) and [Managing HSM users with CloudHSM Management Utility (CMU)](manage-hsm-users-cmu.md)
To specify the CU to PKCS \$111 library, use the pin parameter of the PKCS \$111 [C\$1Login function](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc385057915). For AWS CloudHSM, the pin parameter has the following format:
```
:
```
For example, the following command sets the PKCS \$111 library pin to the CU with user name `CryptoUser` and password `CUPassword123!`.
```
CryptoUser:CUPassword123!
```
# Supported key types for the PKCS \$111 library for AWS CloudHSM Client SDK 5
The PKCS \$111 library for AWS CloudHSM Client SDK 5supports the following key types.
****
| Key Type | Description |
| --- | --- |
| AES | Generate 128, 192, and 256-bit AES keys. |
| Triple DES (3DES, DESede) | Generate 192-bit Triple DES keys. See note [1](#key-types-1) below for an upcoming change. |
| EC | Generate keys with the secp224r1 (P-224), secp256r1 (P-256), secp256k1 (Blockchain), secp384r1 (P-384), and secp521r1 (P-521) curves. |
| GENERIC\$1SECRET | Generate 1 to 800 bytes generic secrets. |
| RSA | Generate 2048-bit to 4096-bit RSA keys, in increments of 256 bits. |
[1] In accordance with NIST guidance, this is disallowed for clusters in FIPS mode after 2023. For clusters in non-FIPS mode, it is still allowed after 2023. See [FIPS 140 Compliance: 2024 Mechanism Deprecation](compliance-dep-notif.md#compliance-dep-notif-1) for details.
# Supported mechanisms for the PKCS \$111 library for AWS CloudHSM Client SDK 5
The PKCS \$111 library is compliant with version 2.40 of the PKCS \$111 specification. To invoke a cryptographic feature using PKCS \$111, call a function with a given mechanism. The following sections summarize the combinations of functions and mechanisms supported by AWS CloudHSM Client SDK 5.
The PKCS \$111 library supports the following algorithms:
+ **Encryption and decryption** – AES-CBC, AES-CTR, AES-ECB, AES-GCM, DES3-CBC, DES3-ECB, RSA-OAEP, and RSA-PKCS
+ **Sign and verify** – RSA, HMAC, and ECDSA; with and without hashing
+ **Hash/digest** – SHA1, SHA224, SHA256, SHA384, and SHA512
+ **Key wrap** – AES Key Wrap[1](#mech1), AES-GCM, RSA-AES, and RSA-OAEP
+ **Key derivation** – SP800-108 Counter KDF and ECDH with KDF (Supported KDF algorithms are X9.63 with SHA1, SHA224, SHA256, SHA384, SHA512)
**Topics**
+ [Generate key and key pair functions](#pkcs11-mech-function-genkey)
+ [Sign and verify functions](#pkcs11-mech-function-signverify)
+ [Sign recover and verify recover functions](#pkcs11-mech-function-sr-vr)
+ [Digest functions](#pkcs11-mech-function-digest)
+ [Encrypt and decrypt functions](#pkcs11-mech-function-enc-dec)
+ [Derive key functions](#pkcs11-mech-function-derive-key)
+ [Wrap and Unwrap functions](#pkcs11-mech-function-wrap-unwrap)
+ [Maximum data size for each mechanism](#pkcs11-mech-max)
+ [Mechanism annotations](#pkcs11-mech-annotations)
## Generate key and key pair functions
The AWS CloudHSM software library for PKCS \$111 library allows you to use the following mechanisms for Generate Key and Key Pair functions.
+ `CKM_RSA_PKCS_KEY_PAIR_GEN`
+ `CKM_RSA_X9_31_KEY_PAIR_GEN` – This mechanism is functionally identical to the `CKM_RSA_PKCS_KEY_PAIR_GEN` mechanism, but offers stronger guarantees for `p` and `q` generation.
+ `CKM_EC_KEY_PAIR_GEN`
+ `CKM_GENERIC_SECRET_KEY_GEN`
+ `CKM_AES_KEY_GEN`
+ `CKM_DES3_KEY_GEN` – upcoming change listed in footnote [5](#mech5).
## Sign and verify functions
The AWS CloudHSM software library for PKCS \$111 library allows you to use the following mechanisms for Sign and Verify functions. With Client SDK 5, the data is hashed locally in software. This means there is no limit on the size of the data that can be hashed by the SDK.
With Client SDK 5 RSA and ECDSA hashing is done locally so there is no data limit. With HMAC, there is a data limit. See footnote [2](#mech2) for more info.
**RSA**
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS` – single-part operations only.
+ `CKM_RSA_PKCS_PSS` – single-part operations only.
+ `CKM_SHA1_RSA_PKCS`
+ `CKM_SHA224_RSA_PKCS`
+ `CKM_SHA256_RSA_PKCS`
+ `CKM_SHA384_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA1_RSA_PKCS_PSS`
+ `CKM_SHA224_RSA_PKCS_PSS`
+ `CKM_SHA256_RSA_PKCS_PSS`
+ `CKM_SHA384_RSA_PKCS_PSS`
+ `CKM_SHA512_RSA_PKCS_PSS`
**ECDSA**
+ `CKM_ECDSA` – single-part operations only.
+ `CKM_ECDSA_SHA1`
+ `CKM_ECDSA_SHA224`
+ `CKM_ECDSA_SHA256`
+ `CKM_ECDSA_SHA384`
+ `CKM_ECDSA_SHA512`
**HMAC**
+ `CKM_SHA_1_HMAC`[2](#mech2)
+ `CKM_SHA224_HMAC`[2](#mech2)
+ `CKM_SHA256_HMAC`[2](#mech2)
+ `CKM_SHA384_HMAC`[2](#mech2)
+ `CKM_SHA512_HMAC`[2](#mech2)
**CMAC**
+ `CKM_AES_CMAC`
## Sign recover and verify recover functions
Client SDK 5 does not support Sign Recover and Verify Recover functions.
## Digest functions
The AWS CloudHSM software library for PKCS \$111 library allows you to use the following mechanisms for Digest functions. With Client SDK 5, the data is hashed locally in software. This means there is no limit on the size of the data that can be hashed by the SDK.
+ `CKM_SHA_1`
+ `CKM_SHA224`
+ `CKM_SHA256`
+ `CKM_SHA384`
+ `CKM_SHA512`
## Encrypt and decrypt functions
The AWS CloudHSM software library for PKCS \$111 library allows you to use the following mechanisms for Encrypt and Decrypt functions.
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS` – single-part operations only. Upcoming change listed in footnote [5](#mech5).
+ `CKM_RSA_PKCS_OAEP` – single-part operations only.
+ `CKM_AES_ECB`
+ `CKM_AES_CTR`
+ `CKM_AES_CBC`
+ `CKM_AES_CBC_PAD`
+ `CKM_DES3_CBC` – upcoming change listed in footnote [5](#mech5).
+ `CKM_DES3_ECB` – upcoming change listed in footnote [5](#mech5).
+ `CKM_DES3_CBC_PAD` – upcoming change listed in footnote [5](#mech5).
+ `CKM_AES_GCM` [1](#mech1), [2](#mech2)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
## Derive key functions
The AWS CloudHSM software library for PKCS \$111 library supports the following key derivation mechanisms:
+ `CKM_SP800_108_COUNTER_KDF`
+ `CKM_ECDH1_DERIVE` - Supports ECDH key derivation with the following vendor-defined KDF types[6](#kdf6):
+ `CKD_CLOUDHSM_X963_SHA1_KDF` - X9.63 KDF with SHA1[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA224_KDF` - X9.63 KDF with SHA224[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA256_KDF` - X9.63 KDF with SHA256[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA384_KDF` - X9.63 KDF with SHA384[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA512_KDF` - X9.63 KDF with SHA512[7](#kdf7)
## Wrap and Unwrap functions
The AWS CloudHSM software library for PKCS \$111 library allows you to use the following mechanisms for Wrap and Unwrap functions.
For additional information regarding AES key wrapping, see [AES Key Wrapping](manage-aes-key-wrapping.md).
+ `CKM_RSA_PKCS` – single-part operations only. An upcoming change is listed in footnote [5](#mech5).
+ `CKM_RSA_PKCS_OAEP`[4](#mech4)
+ `CKM_AES_GCM`[1](#mech1), [3](#mech3)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
+ `CKM_RSA_AES_KEY_WRAP`
+ `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`[3](#mech3)
## Maximum data size for each mechanism
The following table lists the maximum data size set for each mechanism:
**Maximum data set size**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-mechanisms.html)
## Mechanism annotations
+ [1] When performing AES-GCM encryption, the HSM does not accept initialization vector (IV) data from the application. You must use an IV that it generates. The 12-byte IV provided by the HSM is written into the memory reference pointed to by the pIV element of the `CK_GCM_PARAMS` parameters structure that you supply. To prevent user confusion, PKCS \$111 SDK in version 1.1.1 and later ensures that pIV points to a zeroized buffer when AES-GCM encryption is initialized.
+ [2] When operating on data by using any of the following mechanisms, if the data buffer exceeds the maximum data size, the operation results in an error. For these mechanisms, all the data processing must occur inside the HSM. For information on maximum data size sets for each mechanism, refer to [Maximum data size for each mechanism](#pkcs11-mech-max).
+ [3] Vendor-defined mechanism. In order to use the CloudHSM vendor defined mechanisms, PKCS\$111 applications must include `/opt/cloudhsm/include/pkcs11/pkcs11t.h` during compilation.
`CKM_CLOUDHSM_AES_GCM`: This proprietary mechanism is a programmatically safer alternative to the standard `CKM_AES_GCM`. It prepends the IV generated by the HSM to the ciphertext instead of writing it back into the `CK_GCM_PARAMS` structure that is provided during cipher initialization. You can use this mechanism with `C_Encrypt`, `C_WrapKey`, `C_Decrypt`, and `C_UnwrapKey` functions. When using this mechanism, the pIV variable in the `CK_GCM_PARAMS` struct must be set to `NULL`. When using this mechanism with `C_Decrypt` and `C_UnwrapKey`, the IV is expected to be prepended to the ciphertext that is being unwrapped.
`CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`: AES Key Wrap with PKCS \$15 Padding.
`CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`: AES Key Wrap with Zero Padding.
+ [4] The following `CK_MECHANISM_TYPE` and `CK_RSA_PKCS_MGF_TYPE` are supported as `CK_RSA_PKCS_OAEP_PARAMS` for `CKM_RSA_PKCS_OAEP`:
+ `CKM_SHA_1` using `CKG_MGF1_SHA1`
+ `CKM_SHA224` using `CKG_MGF1_SHA224`
+ `CKM_SHA256` using `CKG_MGF1_SHA256`
+ `CKM_SHA384` using `CKM_MGF1_SHA384`
+ `CKM_SHA512` using `CKM_MGF1_SHA512`
+ [5] In accordance with NIST guidance, this is disallowed for clusters in FIPS mode after 2023. For clusters in non-FIPS mode, it is still allowed after 2023. See [FIPS 140 Compliance: 2024 Mechanism Deprecation](compliance-dep-notif.md#compliance-dep-notif-1) for details.
+ [6] Vendor defined types. In order to use CloudHSM vendor defined types, PKCS\$111 applications must include `cloudhsm_pkcs11_vendor_defs.h` during compilation. This is found in `/opt/cloudhsm/include/pkcs11/cloudhsm_pkcs11_vendor_defs.h` for Linux based platforms and `C:\Program Files\Amazon\CloudHSM\include\pkcs11\cloudhsm_pkcs11_vendor_defs.h` for Windows based platforms
+ [7] Key derivation functions (KDFs) are specified in [NIST Special Publication 800-56A Revision 3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf).
# Supported API operations for the PKCS \$111 library for AWS CloudHSM Client SDK 5
The PKCS \$111 library supports the following PKCS \$111 API operations for AWS CloudHSM Client SDK 5.
+ `C_CloseAllSessions`
+ `C_CloseSession`
+ `C_CreateObject`
+ `C_Decrypt`
+ `C_DecryptFinal`
+ `C_DecryptInit`
+ `C_DecryptUpdate`
+ `C_DeriveKey`
+ `C_DestroyObject`
+ `C_Digest`
+ `C_DigestFinal`
+ `C_DigestInit`
+ `C_DigestUpdate`
+ `C_Encrypt`
+ `C_EncryptFinal`
+ `C_EncryptInit`
+ `C_EncryptUpdate`
+ `C_Finalize`
+ `C_FindObjects`
+ `C_FindObjectsFinal`
+ `C_FindObjectsInit`
+ `C_GenerateKey`
+ `C_GenerateKeyPair`
+ `C_GenerateRandom`
+ `C_GetAttributeValue`
+ `C_GetFunctionList`
+ `C_GetInfo`
+ `C_GetMechanismInfo`
+ `C_GetMechanismList`
+ `C_GetSessionInfo`
+ `C_GetSlotInfo`
+ `C_GetSlotList`
+ `C_GetTokenInfo`
+ `C_Initialize`
+ `C_Login`
+ `C_Logout`
+ `C_OpenSession`
+ `C_Sign`
+ `C_SignFinal`
+ `C_SignInit`
+ `C_SignUpdate`
+ `C_UnWrapKey`
+ `C_Verify`
+ `C_VerifyFinal`
+ `C_VerifyInit`
+ `C_VerifyUpdate`
+ `C_WrapKey`
# Key attributes in the PKCS \$111 library for AWS CloudHSM Client SDK 5
An AWS CloudHSM key object can be a public, private, or secret key. Actions permitted on a key object are specified through attributes. Attributes are defined when the key object is created. When you use the PKCS \$111 library for AWS CloudHSM, we assign default values as specified by the PKCS \$111 standard.
AWS CloudHSM does not support all attributes listed in the PKCS \$111 specification. We are compliant with the specification for all attributes we support. These attributes are listed in the respective tables.
Cryptographic functions such as `C_CreateObject`, `C_GenerateKey`, `C_GenerateKeyPair`, `C_UnwrapKey`, and `C_DeriveKey` that create, modify, or copy objects take an attribute template as one of their parameters. For more information about passing an attribute template during object creation, see [Generate keys through PKCS \$111 library](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate) for examples.
The following topics provide more information about AWS CloudHSM key attributes.
**Topics**
+ [Attributes tables](pkcs11-attributes-interpreting.md)
+ [Modifying attributes](modify-attr.md)
+ [Interpreting error codes](attr-errors.md)
# PKCS \$111 library attributes tables for AWS CloudHSM Client SDK 5
The PKCS \$111 library tables for AWS CloudHSM contain a list of attributes that differ by key types. It indicates whether a given attribute is supported for a particular key type when using a specific cryptographic function with AWS CloudHSM.
**Legend:**
+ ✔ indicates that CloudHSM supports the attribute for the specific key type.
+ ✖ indicates that CloudHSM does not support the attribute for the specific key type.
+ R indicates that the attribute value is set to read-only for the specific key type.
+ S indicates that the attribute cannot be read by the `GetAttributeValue` as it is sensitive.
+ An empty cell in the Default Value column indicates that there is no specific default value assigned to the attribute.
## GenerateKeyPair
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GenerateKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## CreateObject
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## UnwrapKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## DeriveKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GetAttributeValue
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
**Attribute annotations**
+ [1] This attribute is partially supported by the firmware and must be explicitly set only to the default value.
+ [2] Mandatory attribute.
# Modifying PKCS \$111 library attributes for AWS CloudHSM Client SDK 5
Some PKCS \$111 library attributes for of an AWS CloudHSM object can be modified after the object has been created, whereas some cannot. To modify attributes, use the [key set-attribute](cloudhsm_cli-key-set-attribute.md) command from CloudHSM CLI. You can also derive a list of attributes by using the [key list](cloudhsm_cli-key-list.md) command from CloudHSM CLI.
The following list displays attributes that are allowed for modification after object creation:
+ `CKA_LABEL`
+ `CKA_TOKEN`
**Note**
Modification is allowed only for changing a session key to a token key. Use the [key set-attribute](cloudhsm_cli-key-set-attribute.md) command from CloudHSM CLI to change the attribute value.
+ `CKA_ENCRYPT`
+ `CKA_DECRYPT`
+ `CKA_SIGN`
+ `CKA_VERIFY`
+ `CKA_WRAP`
+ `CKA_UNWRAP`
+ `CKA_LABEL`
+ `CKA_SENSITIVE`
+ `CKA_DERIVE`
**Note**
This attribute supports key derivation. It must be `False` for all public keys and cannot be set to `True`. For secret and EC private keys, it can be set to `True` or `False`.
+ `CKA_TRUSTED`
**Note**
This attribute can be set to `True` or `False` by Crypto Officer (CO) only.
+ `CKA_WRAP_WITH_TRUSTED`
**Note**
Apply this attribute to an exportable data key to specify that you can only wrap this key with keys marked as `CKA_TRUSTED`. Once you set `CKA_WRAP_WITH_TRUSTED` to true, the attribute becomes read-only and you cannot change or remove the attribute.
# Interpreting PKCS \$111 library error codes for AWS CloudHSM Client SDK 5
Specifying in the template a PKCS \$111 library attribute that is not supported by a specific key results in an error. The following table contains error codes that are generated when you violate specifications:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/attr-errors.html)
# Code samples for the PKCS \$111 library for AWS CloudHSM Client SDK 5
The code samples on GitHub show you how to accomplish basic tasks using the PKCS \$111 library for AWS CloudHSM Client SDK 5.
## Prerequisites
Before running samples, perform the following steps to set up your environment:
+ Install and configure the [PKCS \$111 library](pkcs11-library-install.md) for Client SDK 5.
+ Set up a [cryptographic user (CU)](manage-hsm-users.md). Your application uses this HSM account to run the code samples on the HSM.
## Code samples
Code Samples for the AWS CloudHSM Software Library for PKCS\$111 are available on [GitHub](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples). This repository includes examples on how to do common operations using PKCS\$111 including encryption, decryption, signing and verifying.
+ [Generate keys (AES, RSA, EC)](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate)
+ [List key attributes](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/attributes/)
+ [Encrypt and decrypt data with AES GCM](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/encrypt/aes_gcm.c)
+ [Encrypt and decrypt data with AES\$1CTR](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/aes_ctr.c)
+ [Encrypt and decrypt data with 3DES](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/des_ecb.c)
+ [Sign and verify data with RSA](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/sign/rsa_sign.c)
+ [Derive keys using HMAC KDF](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/derivation/hmac_kdf.c)
+ [Wrap and unwrap keys with AES using PKCS \$15 padding](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_wrapping.c)
+ [Wrap and unwrap keys with AES using no padding](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_no_padding_wrapping.c)
+ [Wrap and unwrap keys with AES using zero padding](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_zero_padding_wrapping.c)
+ [Wrap and unwrap keys with AES-GCM](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/wrapping/aes_gcm_wrapping.c)
+ [Wrap and unwrap keys with RSA](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/rsa_wrapping.c)
# Advanced configurations for PKCS \$111 library for AWS CloudHSM
The AWS CloudHSM PKCS \$111 provider includes the following advanced configuration, which is not part of the general configurations most customers utilize. These configurations provide additional capabilities.
+ [Connecting to multiple slots with PKCS \$111](pkcs11-library-configs-multi-slot.md)
+ [Retry configuration for PKCS \$111](pkcs11-library-configs-retry.md)
# Multiple slot configuration with PKCS \$111 library for AWS CloudHSM
A single slot in Client SDK 5 PKCS \$111 library represents a single connection to a cluster in AWS CloudHSM. With Client SDK 5, you can configure your PKCS11 library to allow multiple slots to connect users to multiple CloudHSM clusters from a single PKCS\$111 application.
Use the instructions in this topic to make your application use multi-slot functionality to connect with multiple clusters.
**Topics**
+ [Multi-slot prerequisites for PKCS \$111 library for AWS CloudHSM](#pkcs11-multi-slot-prereqs)
+ [Configure the PKCS \$111 library for multi-slot functionality for AWS CloudHSM](pkcs11-multi-slot-config-run.md)
+ [Add a cluster with multi-slot functionality for AWS CloudHSM](pkcs11-multi-slot-add-cluster.md)
+ [Remove a cluster with multi-slot functionality for AWS CloudHSM](pkcs11-multi-slot-remove-cluster.md)
## Multi-slot prerequisites for PKCS \$111 library for AWS CloudHSM
Before configuring for multiple slots for PKCS \$111 library for AWS CloudHSM, complete the following prerequisites.
+ Two or more AWS CloudHSM clusters to which you’d like to connect to, along with their cluster certificates.
+ An EC2 instance with Security Groups correctly configured to connect to all of the clusters above. For more information about how to set up a cluster and the client instance, refer to [Getting started with AWS CloudHSM](getting-started.md).
+ To set up multi-slot functionality, you must have already downloaded and installed the PKCS \$111 library. If you have not already done this, refer to the instructions in [Install the PKCS \$111 library for AWS CloudHSM Client SDK 5](pkcs11-library-install.md).
# Configure the PKCS \$111 library for multi-slot functionality for AWS CloudHSM
To configure your PKCS \$111 library for multi-slot functionality for AWS CloudHSM, follow these steps:
1. Identify the clusters you want to connect to using multi-slot functionality.
1. Add these clusters to your PKCS \$111 configuration by following the instructions in [Add a cluster with multi-slot functionality for AWS CloudHSM](pkcs11-multi-slot-add-cluster.md)
1. The next time your PKCS\$111 application runs, it will have multi-slot functionality.
# Add a cluster with multi-slot functionality for AWS CloudHSM
When [connecting to multiple slots with PKCS \$111](pkcs11-library-configs-multi-slot.md) for AWS CloudHSM, use the **configure-pkcs11 add-cluster** command to add a cluster to your configuration.
## Syntax
```
configure-pkcs11 add-cluster [OPTIONS]
--cluster-id
[--region ]
[--endpoint ]
[--hsm-ca-cert ]
[--client-cert-hsm-tls-file ]
[--client-key-hsm-tls-file ]
[-h, --help]
```
## Examples
### Add a cluster using the `cluster-id` parameter
**Example**
Use the **configure-pkcs11 add-cluster** along with the `cluster-id` parameter to add a cluster (with the ID of `cluster-1234567`) to your configuration.
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id
```
**Tip**
If using **configure-pkcs11 add-cluster** with the `cluster-id` parameter doesn't result in the cluster being added, refer to the following example for a longer version of this command that also requires `--region` and `--endpoint` parameters to identify the cluster being added. If, for example, the region of the cluster is different than the one configured as your AWS CLI default, you should use the `--region` parameter to use the correct region. Additionally, you have the ability to specify the AWS CloudHSM API endpoint to use for the call, which may be necessary for various network setups, such as using VPC interface endpoints that don’t use the default DNS hostname for AWS CloudHSM.
### Add a cluster using `cluster-id`, `endpoint`, and `region` parameters
**Example**
Use the **configure-pkcs11 add-cluster** along with the `cluster-id`, `endpoint`, and `region` parameters to add a cluster (with the ID of `cluster-1234567`) to your configuration.
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id --region --endpoint
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id --region --endpoint
```
For more information about the `--cluster-id`, `--region`, and `--endpoint` parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md).
## Parameters
**--cluster-id ****
Makes a `DescribeClusters` call to find all of the HSM elastic network interface (ENI) IP addresses in the cluster associated with the cluster ID. The system adds the ENI IP addresses to the AWS CloudHSM configuration files.
If you use the `--cluster-id` parameter from an EC2 instance within a VPC that does not have access to the public internet, then you must create an interface VPC endpoint to connect with AWS CloudHSM. For more information about VPC endpoints, see [AWS CloudHSM and VPC endpoints](cloudhsm-vpc-endpoint.md).
Required: Yes
**--endpoint ****
Specify the AWS CloudHSM API endpoint used for making the `DescribeClusters` call. You must set this option in combination with `--cluster-id`.
Required: No
**--hsm-ca-cert ****
Specifies the filepath to the HSM CA certificate.
Required: No
**--region ****
Specify the region of your cluster. You must set this option in combination with `--cluster-id`.
If you don’t supply the `--region` parameter, the system chooses the region by attempting to read the `AWS_DEFAULT_REGION` or `AWS_REGION` environment variables. If those variables aren’t set, then the system checks the region associated with your profile in your AWS config file (typically `~/.aws/config`) unless you specified a different file in the `AWS_CONFIG_FILE` environment variable. If none of the above are set, the system defaults to the `us-east-1` region.
Required: No
**--client-cert-hsm-tls-file ****
Path to the client certificate used for TLS client-HSM mutual authentication.
Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with `--client-key-hsm-tls-file`.
Required: No
**--client-key-hsm-tls-file ****
Path to the client key used for TLS client-HSM mutual authentication.
Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with `--client-cert-hsm-tls-file`.
Required: No
# Remove a cluster with multi-slot functionality for AWS CloudHSM
When [connecting to multiple slots with PKCS\$111](pkcs11-library-configs-multi-slot.md), use the **configure-pkcs11 remove-cluster** command to remove a cluster from available PKCS \$111 slots.
## Syntax
```
configure-pkcs11 remove-cluster [OPTIONS]
--cluster-id
[-h, --help]
```
## Examples
### Remove a cluster using the `cluster-id` parameter
**Example**
Use the **configure-pkcs11 remove-cluster** along with the `cluster-id` parameter to remove a cluster (with the ID of `cluster-1234567`) from your configuration.
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 remove-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" remove-cluster --cluster-id
```
For more information about the `--cluster-id` parameter, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md).
## Parameter
**--cluster-id ****
The ID of the cluster to remove from the configuration
Required: Yes
# Retry commands for PKCS \$111 library for AWS CloudHSM
AWS CloudHSM Client SDK 5.8.0 and later have a built-in automatic retry strategy which will retry HSM-throttled operations from the client side. When an HSM throttles operations because it is too busy performing previous operations and cannot take more requests, client SDKs will attempt to retry throttled operations up to 3 times while exponentially backing off. This automatic retry strategy can be set to one of two modes: **off** and **standard**.
+ **off**: The Client SDK will not perform any retry strategy for any throttled operations by the HSM.
+ **standard**: This is the default mode for Client SDK 5.8.0 and later. In this mode, client SDKs will automatically retry throttled operations by exponentially backing off.
For more information, see [HSM throttling](troubleshoot-hsm-throttling.md).
## Set retry commands to off mode
------
#### [ Linux ]
**To set retry commands to **off** for Client SDK 5 on Linux**
+ You can use the following command to set retry configuration to **off** mode:
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 --default-retry-mode off
```
------
#### [ Windows ]
**To set retry commands to **off** for Client SDK 5 on Windows**
+ You can use the following command to set retry configuration to **off** mode:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --default-retry-mode off
```
------
# Certificate storage with the PKCS \$111 library
The AWS CloudHSM PKCS \$111 library supports storing public key certificates as "public objects" (as defined in PKCS \$111 2.40) on hsm2m.medium clusters. This feature allows both public and private PKCS \$111 sessions to create, retrieve, modify, and delete public key certificates.
To use certificate storage with the PKCS \$111 library, you need to enable it in your client configuration. Once enabled, you can manage certificate objects from your PKCS \$111 applications. Operations that apply to both certificate and key objects, such as [C\$1FindObjects](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc323205461), will return results from both key and certificate storage.
**Topics**
+ [Enable certificate storage](pkcs11-certificate-storage-configuration.md)
+ [Certificate storage API](pkcs11-certificate-storage-api.md)
+ [Certificate attributes](pkcs11-certificate-storage-attributes.md)
+ [Certificate storage audit logs](pkcs11-certificate-storage-audit-logs.md)
# Enabling certificate storage
You can enable certificate storage on hsm2m.medium clusters using the PKCS \$111 library configuration tool. This feature is available in SDK versions 5.13 and later. For a list of operations that support the certificate object type, see [Certificate storage API operations](pkcs11-certificate-storage-api.md).
To enable certificate storage, follow these steps for your operating system:
------
#### [ Linux ]
+
****Enable certificate storage****
Run the following command:
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 --enable-certificate-storage
```
------
#### [ Windows ]
+
****Enable certificate storage****
Open a command prompt and run the following command:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --enable-certificate-storage
```
------
# Certificate storage API operations
The following PKCS \$111 operations support the certificate object type (`CKO_CERTIFICATE`):
## General certificate operations
**`C_CreateObject`**
Creates a new certificate object.
**`C_DestroyObject`**
Deletes an existing certificate object.
**`C_GetAttributeValue`**
Gets the value of one or more attributes of a certificate object.
**`C_SetAttributeValue`**
Updates the value of one or more attributes of a certificate object.
## Certificate object search operations
**`C_FindObjectsInit`**
Starts a search for certificate objects.
**`C_FindObjects`**
Continues a search for certificate objects.
**`C_FindObjectsFinal`**
Ends a search for certificate objects.
# Certificate storage attributes
The following table lists the supported certificate object attributes and their values:
| Attribute | Default value | Description |
| --- | --- | --- |
| `CKA_CLASS` | Required | Must be `CKO_CERTIFICATE`. |
| `CKA_TOKEN` | True | Must be `True`. |
| `CKA_MODIFIABLE` | True | Must be `True`. |
| `CKA_PRIVATE` | False | Must be `False`. |
| `CKA_LABEL` | Empty | Limit 127 characters. |
| `CKA_COPYABLE` | False | Must be `False`. |
| `CKA_DESTROYABLE` | True | Must be `True`. |
| `CKA_CERTIFICATE_TYPE` | Required | Must be `CKC_X_509`. |
| `CKA_TRUSTED` | False | Must be `False`. |
| `CKA_CERTIFICATE_CATEGORY` | `CK_CERTIFICATE_CATEGORY_UNSPECIFIED` | Must be `CK_CERTIFICATE_CATEGORY_UNSPECIFIED`. |
| `CKA_CHECK_VALUE` | Derived from `CKA_VALUE` | Automatically set based on `CKA_VALUE`. |
| `CKA_START_DATE` | Empty | The certificate 'not before' date. |
| `CKA_END_DATE` | Empty | The certificate 'not after' date. |
| `CKA_PUBLIC_KEY_INFO` | Empty | Maximum size is 16 kilobytes. |
| `CKA_SUBJECT` | Required | The certificate subject. |
| `CKA_ID` | Empty | Maximum size is 128 bytes. Uniqueness isn't enforced. |
| `CKA_ISSUER` | Empty | The certificate issuer. |
| `CKA_SERIAL_NUMBER` | Empty | The certificate serial number. |
| `CKA_VALUE` | Required | Maximum size is 32 kilobytes. |
# Certificate storage audit logs
AWS CloudHSM writes audit logs for certificate storage operations that modify data to a separate Amazon CloudWatch Events log stream within your cluster's CloudWatch log group. This log stream is named for the cluster, not for a specific HSM within the cluster.
For information about accessing audit logs in CloudWatch, see [Working with Amazon CloudWatch Logs and AWS CloudHSM Audit Logs](get-hsm-audit-logs-using-cloudwatch.md).
## Log entry fields
`object_handle`
The unique identifier of the certificate object.
`op_code`
The operation performed or attempted. Possible values:
+ `CreateObject`
+ `DestroyObject`
+ `SetAttributeValues`
`response`
`OK` if the operation succeeded, or one of the following error types:
+ `DuplicateAttribute`
+ `InvalidAttributeValue`
+ `ObjectNotFound`
+ `MaxObjectsReached`
+ `InternalFailure`
`attributes`
The attributes modified, if any.
`timestamp`
The time when the operation occurred, in milliseconds since the Unix epoch.
## Audit log examples
### CreateObject example
```
{
"object_handle": 463180677312929947,
"op_code": "CreateObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482483671
}
```
### DestroyObject example
```
{
"object_handle": 463180677312929947,
"op_code": "DestroyObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482484559
}
```
### SetAttributeValues example
```
{
"object_handle": 463180678453346687,
"op_code": "SetAttributeValues",
"response": "OK",
"attributes": [
"Label"
],
"timestamp": 1725482488004
}
```
### Unsuccessful CreateObject example
```
{
"object_handle": null,
"op_code": "CreateObject",
"response": "MaxObjectsReached",
"attributes": null,
"timestamp": 1726084937125
}
```
# OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5
The AWS CloudHSM OpenSSL Dynamic Engine allows you to offload cryptographic operations to your CloudHSM cluster through the OpenSSL API.
AWS CloudHSM provides an OpenSSL Dynamic Engine, which you can read about in [AWS CloudHSM SSL/TLS offload on Linux using Tomcat with JSSE](third-offload-linux-jsse.md) or [AWS CloudHSM SSL/TLS offload on Linux using NGINX or Apache with OpenSSL](third-offload-linux-openssl.md). For an example on using AWS CloudHSM with OpenSSL, refer to [this AWS security blog](https://aws.amazon.com/blogs/security/automate-the-deployment-of-an-nginx-web-service-using-amazon-ecs-with-tls-offload-in-cloudhsm/). For information about platform support for SDKs, see [AWS CloudHSM Client SDK 5 supported platforms](client-supported-platforms.md). For troubleshooting, see [Known issues for the OpenSSL Dynamic Engine for AWS CloudHSM](ki-openssl-sdk.md).
Use the following sections to install and configure the AWS CloudHSM dynamic engine for OpenSSL, using Client SDK 5.
For information on using Client SDK 3, see [Using previous SDK version to work with AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl5-install.md)
+ [Supported key types for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl-key-types.md)
+ [Supported mechanisms for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl-mechanisms.md)
+ [Advanced configurations for OpenSSL for AWS CloudHSM](openssl-library-configs.md)
# Install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5
Use the following sections to install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5.
**Note**
To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](manage-key-sync.md) and [Client SDK 5 Configure Tool](configure-sdk-5.md).
**To install and configure the OpenSSL Dynamic Engine**
1. Use the following commands to download and install the OpenSSL engine.
------
#### [ Amazon Linux 2023 ]
Install the OpenSSL Dynamic Engine for Amazon Linux 2023 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
Install the OpenSSL Dynamic Engine for Amazon Linux 2023 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
Install the OpenSSL Dynamic Engine for Amazon Linux 2 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.x86_64.rpm
```
Install the OpenSSL Dynamic Engine for Amazon Linux 2 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Install the OpenSSL Dynamic Engine for RHEL 9 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.x86_64.rpm
```
Install the OpenSSL Dynamic Engine for RHEL 9 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
Install the OpenSSL Dynamic Engine for RHEL 8 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.x86_64.rpm
```
Install the OpenSSL Dynamic Engine for RHEL 8 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Install the OpenSSL Dynamic Engine for Ubuntu 24.04 LTS on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_amd64.deb
```
Install the OpenSSL Dynamic Engine for Ubuntu 24.04 LTS on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Install the OpenSSL Dynamic Engine for Ubuntu 22.04 LTS on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_amd64.deb
```
Install the OpenSSL Dynamic Engine for Ubuntu 22.04 LTS on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_arm64.deb
```
------
You have installed the shared library for the dynamic engine at `/opt/cloudhsm/lib/libcloudhsm_openssl_engine.so`.
1. Bootstrap Client SDK 5. For more information about bootstrapping, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. Set an environment variable with the credentials of a crypto user (CU). For information about creating CUs, see [Create an AWS CloudHSM user with CloudHSM CLI](cloudhsm_cli-user-create.md).
```
$ export CLOUDHSM_PIN=:
```
**Note**
Client SDK 5 introduces the `CLOUDHSM_PIN` environment variable for storing the credentials of the CU. In Client SDK 3 you store the CU credentials in the `n3fips_password` environment variable. Client SDK 5 supports both environment variables, but we recommend using `CLOUDHSM_PIN`.
When setting `CLOUDHSM_PIN` environment variables, you must escape any special characters that may be interpreted by your shell.
1. Connect your installation of OpenSSL Dynamic Engine to the cluster. For more information, see [Connect to the Cluster](cluster-connect.md).
1. Bootstrap the Client SDK 5. For more information, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
## Verify the OpenSSL Dynamic Engine for Client SDK 5
Use the following command to verify your installation of OpenSSL Dynamic Engine.
```
$ openssl engine -t cloudhsm
```
The following output verifies your configuration:
```
(cloudhsm) CloudHSM OpenSSL Engine
[ available ]
```
# Supported key types for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5
The AWS CloudHSM OpenSSL Dynamic Engine supports the following key types with Client SDK 5.
****
| Key Type | Description |
| --- | --- |
| EC | ECDSA sign/verify for P-256, P-384, and secp256k1 key types. To generate EC keys that are interoperable with the OpenSSL engine, see [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md). |
| RSA | RSA key generation for 2048, 3072, and 4096-bit keys.RSA sign/verify. Verification is offloaded to OpenSSL software. |
# Supported mechanisms for OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5
The AWS CloudHSM OpenSSL Dynamic Engine supports the following mechanisms for Sign and Verify functions with Client SDK 5.
## Sign and verify functions
With Client SDK 5, the data is hashed locally in software. This means there is no limit on the size of the data that can be hashed.
RSA Signature Types
+ SHA1withRSA
+ SHA224withRSA
+ SHA256withRSA
+ SHA384withRSA
+ SHA512withRSA
ECDSA Signature Types
+ SHA1withECDSA
+ SHA224withECDSA
+ SHA256withECDSA
+ SHA384withECDSA
+ SHA512withECDSA
# Advanced configurations for OpenSSL for AWS CloudHSM
The AWS CloudHSM OpenSSL provider includes the following advanced configuration, which is not part of the general configurations most customers utilize. These configurations provide additional capabilities.
+ [Retry commands for OpenSSL](openssl-library-configs-retry.md)
# Retry commands for OpenSSL for AWS CloudHSM
AWS CloudHSM Client SDK 5.8.0 and later have a built-in automatic retry strategy which will retry HSM-throttled operations from the client side. When an HSM throttles operations because it is too busy performing previous operations and cannot take more requests, client SDKs will attempt to retry throttled operations up to 3 times while exponentially backing off. This automatic retry strategy can be set to one of two modes: **off** and **standard**.
+ **off**: The Client SDK will not perform any retry strategy for any throttled operations by the HSM.
+ **standard**: This is the default mode for Client SDK 5.8.0 and later. In this mode, client SDKs will automatically retry throttled operations by exponentially backing off.
For more information, see [HSM throttling](troubleshoot-hsm-throttling.md).
## Set retry commands to off mode
You can use the following command to set retry commands to **off** mode:
```
$ sudo /opt/cloudhsm/bin/configure-dyn --default-retry-mode off
```
# OpenSSL Provider for AWS CloudHSM Client SDK 5
The AWS CloudHSM OpenSSL Provider allows you to offload TLS cryptographic operations to your CloudHSM cluster through the OpenSSL Provider API. The Provider interface is the recommended approach for new deployments using OpenSSL 3.2 and later.
Use the following sections to install and configure the AWS CloudHSM OpenSSL Provider, using Client SDK 5.
**Warning**
Integration with OpenSSL CLI is not currently supported by AWS CloudHSM OpenSSL Provider. See [AWS CloudHSM SSL/TLS offload on Linux using NGINX or HAProxy with OpenSSL Provider](third-offload-linux-openssl-provider.md) for supported integrations.
## Supported platforms
The OpenSSL Provider requires OpenSSL 3.2 or later, available on EL9\$1, Ubuntu 24.04\$1, and Amazon Linux 2023\$1.
Verify compatibility: `openssl version`
**Topics**
+ [Supported platforms](#openssl-provider-supported-platforms)
+ [Install the OpenSSL Provider for AWS CloudHSM Client SDK 5](openssl-provider-install.md)
+ [Supported key types for OpenSSL Provider for AWS CloudHSM Client SDK 5](openssl-provider-key-types.md)
+ [OpenSSL Provider Supported Mechanisms](openssl-provider-mechanisms.md)
+ [OpenSSL Provider Advanced Configuration](openssl-provider-advanced-config.md)
# Install the OpenSSL Provider for AWS CloudHSM Client SDK 5
Use the following sections to install the OpenSSL Provider for AWS CloudHSM Client SDK 5.
**Note**
To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](working-client-sync.md#client-sync-sdk8) and [Client SDK 5 Configure Tool](configure-sdk-5.md).
## Requirements
The OpenSSL Provider requires **hsm2m.medium** cluster types and minimum CloudHSM Client SDK version 5.17.0 or later.
## Install the OpenSSL Provider
**To install the OpenSSL Provider**
1. Use the following commands to download and install the OpenSSL Provider.
------
#### [ Amazon Linux 2023 ]
Install the OpenSSL Provider for Amazon Linux 2023 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
Install the OpenSSL Provider for Amazon Linux 2023 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Install the OpenSSL Provider for RHEL 9 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
Install the OpenSSL Provider for RHEL 9 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
Install the OpenSSL Provider for RHEL 10 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
Install the OpenSSL Provider for RHEL 10 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
------
#### [ Ubuntu 24.04 ]
Install the OpenSSL Provider for Ubuntu 24.04 on x86\$164 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
Install the OpenSSL Provider for Ubuntu 24.04 on ARM64 architecture:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
------
You have installed the shared library for the OpenSSL Provider at `/opt/cloudhsm/lib/licloudhsm_openssl_provider.so`.
1. Bootstrap Client SDK 5. For more information about bootstrapping, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. Set the `CLOUDHSM_PIN` environment variable with your crypto user (CU) credentials:
```
$ export CLOUDHSM_PIN=:
```
1. Connect your installation of OpenSSL Provider to the cluster. For more information, see [Connect to the Cluster](cluster-connect.md).
## Verify the installation
Verify that the OpenSSL Provider is installed correctly:
```
$ CLOUDHSM_PIN=: openssl list -providers -provider cloudhsm
```
You should see output similar to:
```
Providers:
cloudhsm
name: AWS CloudHSM OpenSSL Provider
version: 5.17.0
status: active
default
name: OpenSSL Default Provider
version: 3.2.2
status: active
```
# Supported key types for OpenSSL Provider for AWS CloudHSM Client SDK 5
The AWS CloudHSM OpenSSL Provider supports the following key types with Client SDK 5.
****
| Key Type | Description |
| --- | --- |
| RSA | RSA sign/verify and asymmetric encryption operations. Verification is offloaded to OpenSSL software. To generate RSA keys that are interoperable with the OpenSSL Provider, see [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md). |
| EC | ECDSA sign/verify for P-256, P-384, and P-521 curves. Verification is offloaded to OpenSSL software. To generate EC keys that are interoperable with the OpenSSL Provider, see [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md). |
# OpenSSL Provider Supported Mechanisms
The AWS CloudHSM OpenSSL Provider SDK supports a comprehensive set of cryptographic mechanisms for various operations including digital signatures, asymmetric encryption, symmetric encryption, key exchange, and more.
## RSA signature types
The OpenSSL Provider supports RSA digital signatures with multiple hash algorithms and padding schemes:
SHA1withRSA
RSA signatures with SHA-1 hash algorithm
+ PKCS\$11 v1.5 padding
+ PSS (Probabilistic Signature Scheme) padding
SHA224withRSA
RSA signatures with SHA-224 hash algorithm
+ PKCS\$11 v1.5 padding
+ PSS padding
SHA256withRSA
RSA signatures with SHA-256 hash algorithm
+ PKCS\$11 v1.5 padding
+ PSS padding
SHA384withRSA
RSA signatures with SHA-384 hash algorithm
+ PKCS\$11 v1.5 padding
+ PSS padding
SHA512withRSA
RSA signatures with SHA-512 hash algorithm
+ PKCS\$11 v1.5 padding
+ PSS padding
## ECDSA signature types
The OpenSSL Provider supports ECDSA digital signatures with multiple hash algorithms:
SHA1withECDSA
ECDSA signatures with SHA-1 hash algorithm
SHA224withECDSA
ECDSA signatures with SHA-224 hash algorithm
SHA256withECDSA
ECDSA signatures with SHA-256 hash algorithm
SHA384withECDSA
ECDSA signatures with SHA-384 hash algorithm
SHA512withECDSA
ECDSA signatures with SHA-512 hash algorithm
# OpenSSL Provider Advanced Configuration
The AWS CloudHSM OpenSSL Provider SDK provides advanced configuration options to customize its behavior for different use cases and environments. Use the configure tool to set these options.
+ [Retry configuration for OpenSSL Provider](openssl-provider-configs-retry.md)
# Retry commands for OpenSSL Provider for AWS CloudHSM
AWS CloudHSM Client SDK 5.8.0 and later have a built-in automatic retry strategy which will retry HSM-throttled operations from the client side. When an HSM throttles operations because it is too busy performing previous operations and cannot take more requests, client SDKs will attempt to retry throttled operations up to 3 times while exponentially backing off. This automatic retry strategy can be set to one of two modes: **off** and **standard**.
+ **off**: The Client SDK will not perform any retry strategy for any throttled operations by the HSM.
+ **standard**: This is the default mode for Client SDK 5.8.0 and later. In this mode, client SDKs will automatically retry throttled operations by exponentially backing off.
For more information, see [HSM throttling](troubleshoot-hsm-throttling.md).
## Set retry commands to off mode
------
#### [ Linux ]
**To set retry commands to **off** for Client SDK 5 on Linux**
+ You can use the following command to set retry configuration to **off** mode:
```
$ sudo /opt/cloudhsm/bin/configure-openssl-provider --default-retry-mode off
```
------
# Key storage provider (KSP) for AWS CloudHSM Client SDK 5
Key Storage Provider (KSP) is a cryptographic API specific to the Microsoft Windows operating system. Key Storage Provider (KSP) enables developers to use cryptographic techniques to secure Windows-based applications.
For information about bootstrapping, see [Connecting to the cluster](cluster-connect.md).
For information on using Client SDK 3, see [Using previous SDK version to work with AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Install the Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library-install.md)
+ [Authenticate to the Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library-authentication.md)
+ [Supported key types for Key Storage Provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library--key-types.md)
+ [Supported API operations Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library-apis.md)
+ [Advanced configurations for KSP for AWS CloudHSM](ksp-library-configs.md)
# Install the Key storage provider (KSP) for AWS CloudHSM Client SDK 5
Use the following sections to install the Key storage provider (KSP) for AWS CloudHSM Client SDK 5.
**Note**
To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](manage-key-sync.md) and [Client SDK 5 Configure Tool](configure-sdk-5.md).
**To install and configure the Key Storage Provider (KSP)**
1. Install the Key Storage Provider (KSP) for Windows Server on x86\$164 architecture, open PowerShell as an administrator and run the following command:
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMKSP-latest.msi -Outfile C:\AWSCloudHSMKSP-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMKSP-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
1. Use the configure tool to specify the location of the issuing certificate. For instructions, see [Specify the location of the issuing certificate](cluster-connect.md#specify-cert-location).
1. To connect to your cluster, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. You can find the Key Storage Provider (KSP) files in the following locations:
+ Windows binaries:
```
C:\Program Files\Amazon\CloudHSM
```
Windows configuration scripts and log files:
```
C:\ProgramData\Amazon\CloudHSM
```
# Authenticate to the Key storage provider (KSP) for AWS CloudHSM Client SDK 5
Before you use the Key storage provider (KSP) for AWS CloudHSM Client SDK 5, you must set the login credentials for the HSM on your system. You have two options:
+ Windows Credentials Manager (recommended for better security)
+ System environment variables (simpler setup)
## Windows Credential Manager
You can set up credentials using either the `set_cloudhsm_credentials` utility or the Windows Credentials Manager interface.
+ **Using the `set_cloudhsm_credentials` utility**:
The Windows installer includes the `set_cloudhsm_credentials` utility. You can use this utility to conveniently pass HSM login credentials to Windows Credential Manager. If you want to compile this utility from source, you can use the Python code included in the installer.
1. Navigate to `C:\Program Files\Amazon\CloudHSM\tools\`.
1. Run the following command:
```
set_cloudhsm_credentials.exe --username --password
```
+ **Using the Credential Manager interface**:
1. Open Credential Manager:
+ Enter `credential manager` in the taskbar search box
+ Select **Credential Manager**
1. Select **Windows Credentials** to manage Windows credentials.
1. Select **Add a generic credential**
1. Enter the following details:
+ **Internet or Network Address**: `CLOUDHSM_PIN`.
+ **Username**: **.
+ **Password**: **.
1. Choose **OK**
## System environment variables
You can set system environment variables to identify your HSM and [crypto user](understanding-users.md#crypto-user-chsm-cli) (CU).
**Warning**
Setting credentials through system environment variables stores your password in plaintext on your system. For better security, use Windows Credential Manager instead.
You can set environment variables using:
+ The [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx).
+ The Windows **System Properties** Control Panel (**Advanced** tab).
+ set permanent system environment variables [Programmatic](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx) methods.
To set the system environment variable:
**`CLOUDHSM_PIN=:`**
Identifies a [crypto user](understanding-users.md#crypto-user-chsm-cli) (CU) in the HSM and provides all required login information. Your application authenticates and runs as this CU. The application has the permissions of this CU and can view and manage only the keys that the CU owns and shares. To create a new CU, use the [user create](cloudhsm_cli-user-create.md) command in CloudHSM CLI. To find existing CUs, use the [user list](cloudhsm_cli-user-list.md) command in CloudHSM CLI.
For example:
```
setx /m CLOUDHSM_PIN test_user:password123
```
**Note**
When setting CLOUDHSM\$1PIN environment variables, you must escape any special characters that may be interpreted by your shell.
# Supported key types for Key Storage Provider (KSP) for AWS CloudHSM Client SDK 5
The AWS CloudHSM Key Storage Provider (KSP) supports the following key types with Client SDK 5.
****
| Key Type | Description |
| --- | --- |
| EC | Generate keys with the secp256r1 (P-256), secp384r1 (P-384), and secp521r1 (P-521) curves. |
| RSA | Generate 2048, 3072, and 4096-bit RSA keys. |
# Supported API operations Key storage provider (KSP) for AWS CloudHSM Client SDK 5
The parameters in the KSP are defined by Microsoft KSP. See the [Microsoft documentation](https://learn.microsoft.com/en-us/windows/win32/api/ncrypt/) for more information.
The Key Storage Provider (KSP) supports the following KSP API operations for AWS CloudHSM Client SDK 5.
+ [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)
+ [NCryptOpenKey](ksp-library-apis-open-key.md)
+ [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md)
+ [NCryptGetProperty](ksp-library-apis-get-property.md)
+ [NCryptSetProperty](ksp-library-apis-set-property.md)
+ [NCryptFinalizeKey](ksp-library-apis-finalize-key.md)
+ [NCryptDeleteKey](ksp-library-apis-delete-key.md)
+ [NCryptFreeObject](ksp-library-apis-free-object.md)
+ [NCryptFreeBuffer](ksp-library-apis-free-buffer.md)
+ [NCryptIsAlgSupported](ksp-library-apis-is-alg-supported.md)
+ [NCryptEnumAlgorithms](ksp-library-apis-enum-algorithms.md)
+ [NCryptEnumKeys](ksp-library-apis-enum-keys.md)
+ [NCryptExportKey](ksp-library-apis-export-key.md)
+ [NCryptSignHash](ksp-library-apis-sign-hash.md)
+ [NCryptVerifySignature](ksp-library-apis-verify-signature.md)
# NCryptOpenStorageProvider function with Key Storage Provider (KSP)
The `NCryptOpenStorageProvider` function loads and initializes the Key Storage Provider (KSP).
## Parameters
`phProvider` [out]
A pointer to a `NCRYPT_PROV_HANDLE` variable that stores the provider handle.
`pszProviderName` [in]
A pointer to a null-terminated Unicode string identifying the key storage provider. AWS CloudHSM Key Storage Provider (KSP) supports the following values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-open-provider.html)
Values are wide-character string literal, as indicated by L before the literal.
`dwFlags` [in]
Flags that modify the behavior of the function. No flags are defined for this function.
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
# NCryptOpenKey with Key storage provider (KSP)
The `NCryptOpenKey` function opens a key that exists in the Key Storage Provider (KSP).
## Parameters
`hProvider` [in]
The KSP handle that contains the key. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get the handle.
`phKey` [out]
A pointer to a `NCRYPT_KEY_HANDLE` variable that stores the key handle.
`pszKeyName` [in]
A pointer to a null-terminated Unicode string containing the key name.
`dwLegacyKeySpec` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter.
`dwFlags` [in]
Flags that modify function's behavior. No flags are defined for this function.
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1INVALID\$1HANDLE | The handle in `hProvider` is not valid. |
| NTE\$1BAD\$1KEYSET | The key name provided did not return unique result. |
# NCryptCreatePersistedKey with Key storage provider (KSP)
The `NCryptCreatePersistedKey` function creates a new key and stores it in the Key Storage Provider (KSP). You can use the [`NCryptSetProperty`](ksp-library-apis-set-property.md) function to set its properties after creation. You must call [`NCryptFinalizeKey`](ksp-library-apis-finalize-key.md) before you can use the key.
## Parameters
`hProvider` [in]
The handle of the key storage provider where you will create the key. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get this handle.
`phKey` [out]
The address of an `NCRYPT_KEY_HANDLE` variable that stores the key handle.
`pszAlgId` [in]
A pointer to a null-terminated Unicode string that specifies the cryptographic algorithm identifier for creating the key.
AWS CloudHSM Key Storage Provider (KSP) supports the following algorithms:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
`pszKeyName` [in, optional]
A pointer to a null-terminated Unicode string that contains the name of the key. If this parameter is NULL, this function will create an ephemeral key that is not persisted.
`dwLegacyKeySpec` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter.
`dwFlags` [in]
Flags to modify the function's behavior. Use zero or more of the following values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The function completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1NOT\$1SUPPORTED | The `pszAlgId` parameter contains an unsupported value. |
| NTE\$1EXISTS | A key with the specified name already exists and operation didn't use ` NCRYPT_OVERWRITE_KEY_FLAG`. |
# NCryptGetProperty with Key storage provider (KSP)
The `NCryptGetProperty` function retrieves property values for a key storage object.
## Parameters
`hObject` [in]
The handle of the object whose property you want to retrieve. You can use:
+ A provider handle (`NCRYPT_PROV_HANDLE`)
+ A key handle (`NCRYPT_KEY_HANDLE`)
`pszProperty ` [in]
A pointer to a null-terminated Unicode string containing the property name to retrieve.
When using `NCRYPT_PROV_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
When using `NCRYPT_KEY_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
Values are wide-character string literal, as indicated by L before the literal.
`pbOutput` [out]
The address of a buffer to store the property value. Specify the buffer size using `cbOutput`.
To determine the required buffer size, set this parameter to NULL. The function stores the required size (in bytes) in the location pointed to by `pcbResult`.
`cbOutput` [in]
The size of the `pbOutput` buffer in bytes.
`pcbResult` [out]
A pointer to a DWORD variable that stores the number of bytes copied to the`pbOutput` buffer.
If the `pbOutput` is NULL, this stores the required size (in bytes).
`dwFlags` [in]
Flags to modify the function's behavior. You can use zero or:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
When pszProperty is `NCRYPT_SECURITY_DESCR_PROPERTY`, use one or a combination of:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1NOT\$1SUPPORTED | The `pszAlgId` parameter contains a value that is not supported. |
| NTE\$1INVALID\$1HANDLE | The handle in `hObject` is not valid. |
| NTE\$1BUFFER\$1TOO\$1SMALL | The `cbOutput` parameter is too small for return values. |
# NCryptSetProperty with Key storage provider (KSP)
The `NCryptSetProperty` function sets property values for a key storage object.
## Parameters
`hObject` [in]
The handle of the object whose property you want to set. You can use:
+ A provider handle (`NCRYPT_PROV_HANDLE`)
+ A key handle (`NCRYPT_KEY_HANDLE`)
`pszProperty ` [in]
A pointer to a null-terminated Unicode string containing the property name to retrieve.
When using `NCRYPT_PROV_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
When using `NCRYPT_KEY_HANDLE`, AWS CloudHSM Key Storage Provider (KSP) supports the following KSP identifiers:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
Values are wide-character string literal, as indicated by L before the literal.
`pbInput` [in]
The address of a buffer that contains the new property value. `cbInput` contains the size of the buffer.
`cbInput` [in]
The size of the `pbInput` buffer in bytes.
`dwFlags` [in]
Flags that modify function's behavior. No flags are defined for this function.
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1NOT\$1SUPPORTED | The `pszProperty` parameter contains a value that is not supported. |
| NTE\$1INVALID\$1HANDLE | The handle in `hObject` is not valid. |
| NTE\$1BAD\$1DATA | The data pointed by `pbInput` and `cbInput` is not valid. |
# NCryptFinalizeKey with Key storage provider (KSP)
The `NCryptFinalizeKey` function completes a KSP key. You must call this function before you can use the key.
## Parameters
`hKey` [in]
The handle of the key to complete. Get this handle by calling the [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md) function.
`dwFlags` [in]
Flags to modify the function's behavior. You can use zero or these values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-finalize-key.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1INVALID\$1HANDLE | The handle in `hKey` is not valid. |
| NTE\$1NOT\$1SUPPORTED | The `dwFlags` parameter contains a value that is not supported. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
# NCryptDeleteKey with Key storage provider (KSP)
The `NCryptDeleteKey` function deletes a KSP key from the Key Storage Provider (KSP).
## Parameters
`hKey` [in]
The handle of the key to delete.
`dwFlags` [in]
Flags to modify the function's behavior. You can use zero or more of the following values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-delete-key.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The function was successful. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1INVALID\$1HANDLE | The handle in `hKey` is not valid. |
| NTE\$1INTERNAL\$1ERROR | A internal error happened when deleting key. |
# NCryptFreeObject with Key storage provider (KSP)
The `NCryptFreeObject` function releases provider or key handle from the Key Storage Provider (KSP).
## Parameters
`hObject` [in]
The handle of the object to release. You can use:
+ A provider handle (`NCRYPT_PROV_HANDLE`)
+ A key handle (`NCRYPT_KEY_HANDLE`)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1HANDLE | The handle in `hObject` is not valid. |
# NCryptFreeBuffer with Key storage provider (KSP)
The `NCryptFreeBuffer` function releases a block of memory that was allocated by the Key Storage Provider (KSP).
## Parameters
`pvInput` [in]
The address of the memory to released.
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1FAIL | The operation couldn't complete. |
# NCryptIsAlgSupported with Key storage provider (KSP)
NCryptIsAlgSupported function determines if Key Storage Provider (KSP) supports a specific cryptographic algorithm.
## Parameters
`hProvider` [in]
The handle of the key storage provider. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get the handle.
`pszAlgId` [in]
A pointer to a null-terminated Unicode string that contains the identifier of the cryptographic algorithm to create the key. AWS CloudHSM Key Storage Provider (KSP) supports the following algorithms:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
`dwFlags` [in]
Flags that modify function behavior. This can be zero or the following value:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1NOT\$1SUPPORTED | The `pszAlgId` parameter contains an unsupported value. |
| NTE\$1INVALID\$1HANDLE | The handle in `hProvider` is not valid. |
# NCryptEnumAlgorithms with Key storage provider (KSP)
The `NCryptEnumAlgorithms` function retrieves the names of algorithms that the Key Storage Provider (KSP) supports.
## Parameters
`hProvider` [in]
The handle of the key storage provider for which to enumerate the algorithms. Use the [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) function to get this handle.
`dwAlgOperations` [in]
A set of values that specify which algorithm classes to enumerate. You can use zero to enumerate all algorithms, or combine one or more of these values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
`pdwAlgCount` [out]
The address of a DWORD that stores the number of elements in the `ppAlgList` array.
`ppAlgList` [out]
The address of an `NCryptAlgorithmName` structure pointer that stores an array of registered algorithm names. The `pdwAlgCount` parameter indicates the number of elements in this array.
`dwFlags` [in]
Flags to modify the function's behavior. Use zero or the following value:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1NOT\$1SUPPORTED | The `dwAlgOperations` parameter contains an unsupported value. |
# NCryptEnumKeys with Key storage provider (KSP)
NCryptEnumKeys function lists the keys stored in the Key Storage Provider (KSP).
## Parameters
`hProvider` [in]
The key storage provider handle. Use [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) to get this handle.
`pszScope` [in, unused]
Set this parameter to NULL.
`ppKeyName` [out]
A pointer address to an `NCryptKeyName` structure that stores the key name. To free this memory after use, call `NCryptFreeBuffer`.
`ppEnumState` [in, out]
A VOID pointer address that tracks the enumeration progress. The key storage provider uses this information internally to manage the enumeration sequence. To start a new enumeration from the beginning, set this pointer to NULL.
To free this memory after completing the enumeration, pass this pointer to the `NCryptFreeBuffer`.
`dwFlags` [in]
Flags to modify the function's behavior. This function has no flags.
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1INVALID\$1HANDLE | The handle in `hProvider` is not valid. |
| NTE\$1NO\$1MORE\$1ITEMS | The enumeration has listed all available keys. |
# NCryptExportKey with Key storage provider (KSP)
The `NCryptExportKey` function exports a KSP key to a memory BLOB. This function only supports exporting public keys.
## Parameters
`hKey` [in]
The handle of the key to export.
`hExportKey` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter.
`pszBlobType` [in]
A null-terminated Unicode string that specifies the BLOB type to export. AWS CloudHSM Key Storage Provider (KSP) supports the following values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
`pParameterList` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) doesn't use this parameter.
`pbOutput` [out, optional]
A buffer address to store the key BLOB. Specify the buffer size using `cbOutput`. If set to NULL, the function stores the required size (in bytes) in the DWORD pointed to by `pcbResult`.
`cbOutput` [in]
The size of the `pbOutput` buffer in bytes.
`pcbResult` [out]
A DWORD variable address that stores the number of bytes copied to the `pbOutput` buffer. If `pbOutput` is NULL, the function stores the required buffer size in bytes.
`dwFlags` [in]
Flags that modify how the function works. You can use zero or the following:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1INVALID\$1HANDLE | The handle in `hProvider` is not valid. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1BAD\$1KEY\$1STATE | The key state is not valid. |
| NTE\$1NOT\$1SUPPORTED | The `pszBlobType` or `dwFlags` parameter contains an unsupported value. |
| STATUS\$1INTERNAL\$1ERROR | An internal error happened during the operation. |
# NCryptSignHash with Key storage provider (KSP)
The `NCryptSignHash` function creates a signature of a hash value.
## Parameters
`hKey` [in]
The handle of the key to use to sign the hash.
`pPaddingInfo` [in, optional]
A pointer to a structure containing padding information. The structure type depends on the `dwFlags` value. Use this parameter only with asymmetric keys; set to NULL for other key types.
`pbHashValue` [in]
A pointer to a buffer containing the hash value to sign. Specify the buffer size using `cbHashValue`.
`cbHashValue` [in]
The size, in bytes, of the `pbHashValue` buffer to sign.
`pbSignature` [out]
The address of a buffer to store the signature. Specify the buffer size using `cbSignature`.
To determine the required buffer size, set this parameter to NULL. The function stores the required size (in bytes) in the location pointed to by `pcbResult`.
`cbSignature` [in]
The size of the `pbSignature` buffer in bytes. The function ignores this parameter if `pbSignature` is NULL.
`pcbResult` [out]
A pointer to a DWORD variable that stores the number of bytes copied to the `pbSignature` buffer.
If `pbSignature` is NULL, this stores the required buffer size, in bytes.
`dwFlags` [in]
Flags to modify the function's behavior. The allowed flags depend on your key type. Use one of these values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-sign-hash.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1INVALID\$1HANDLE | The handle in `hKey` is not valid. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1BUFFER\$1TOO\$1SMALL | The `pcbOutput` parameter is too small for return values. |
| NTE\$1BAD\$1KEY\$1STATE | The key state is not valid. |
| NTE\$1INTERNAL\$1ERROR | An internal error happened when signing the hash. |
# NCryptVerifySignature with Key storage provider (KSP)
The `NCryptVerifySignature` function confirms whether a signature matches a specified hash.
## Parameters
`hKey` [in]
The handle of the key to use to decrypt the signature. You must use the public key portion of the key pair that was used to sign the data with the [`NCryptSignHash`](ksp-library-apis-sign-hash.md).
`pPaddingInfo` [in, optional]
A pointer to a structure containing padding information. The structure type depends on the `dwFlags` value. Use this parameter only with asymmetric keys; set to NULL for other key types.
`pbHashValue` [in]
A pointer to a buffer containing the hash value to sign. Specify the buffer size using `cbHashValue`.
`cbHashValue` [in]
The size of the `pbHashValue` buffer in bytes.
`pbSignature` [out]
The address of a buffer containing the signed hash of the data. Use [`NCryptSignHash`](ksp-library-apis-sign-hash.md) to create this signature. Specify the buffer size using `cbSignature`.
`cbSignature` [in]
The size of the `pbSignature` buffer in bytes. Use [`NCryptSignHash`](ksp-library-apis-sign-hash.md) to create the signature.
`dwFlags` [in]
Flags to modify the function's behavior. The allowed flags depend on your key type. Use one of these values:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/ksp-library-apis-verify-signature.html)
## Return Value
The function returns a status code to indicate success or failure.
Common return codes include:
****
| Return code | Description |
| --- | --- |
| ERROR\$1SUCCESS | The operation completed successfully. |
| NTE\$1INVALID\$1PARAMETER | One or more parameters are not valid. |
| NTE\$1FAIL | The operation couldn't complete. |
| NTE\$1INVALID\$1HANDLE | The handle in `hKey` is not valid. |
| NTE\$1BAD\$1FLAGS | The `dwFlags` parameter contains an invalid value. |
| NTE\$1BAD\$1SIGNATURE | The signature was not verified. |
| NTE\$1BAD\$1KEY\$1STATE | The key state is not valid. |
| NTE\$1INTERNAL\$1ERROR | An internal error happened while verifying the signature. |
# Advanced configurations for KSP for AWS CloudHSM
The AWS CloudHSM Key Storage Provider (KSP) includes the following advanced configuration, which is not part of the general configurations most customers utilize. These configurations provide additional capabilities.
+ [SDK3 compatibility mode for KSP](ksp-library-configs-sdk3-compatibility-mode.md)
# SDK3 compatibility mode for Key Storage Provider (KSP) for AWS CloudHSM
Key Storage Provider (KSP) implements different approaches for HSM key interaction:
+ Client SDK 5: Provides direct communication with keys stored in the HSM, eliminating the need for local reference files
+ Client SDK 3: Maintains local files on the Windows server that act as references to keys stored in the HSM, using these files to facilitate key operations
For customers migrating from Client SDK 3 to Client SDK 5, enabling SDK3 compatibility mode option supports operations using existing key reference files while preserving the underlying HSM key storage architecture.
## Enable SDK3 compatibility mode
------
#### [ Windows ]
**To enable SDK3 compatibility mode for Key Storage Provider (KSP) for Client SDK 5 in Windows**
+ You can use the following command to enable SDK3 compatibility mode:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --enable-sdk3-compatibility-mode
```
------
## Disable SDK3 compatibility mode
------
#### [ Windows ]
**To disable SDK3 compatibility mode for Key Storage Provider (KSP) for Client SDK 5 in Windows**
+ You can use the following command to disable SDK3 compatibility mode:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-sdk3-compatibility-mode
```
------
# JCE provider for AWS CloudHSM Client SDK 5
The AWS CloudHSM JCE provider is a provider implementation built from the Java Cryptographic Extension (JCE) provider framework. The JCE allows you to perform cryptographic operations using the Java Development Kit (JDK). In this guide, the AWS CloudHSM JCE provider is sometimes referred to as the JCE provider. Use the JCE provider and the JDK to offload cryptographic operations to the HSM. For troubleshooting, see [Known issues for the JCE SDK for AWS CloudHSM](ki-jce-sdk.md).
For information on using Client SDK 3, see [Using previous SDK version to work with AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Install the JCE provider for AWS CloudHSM Client SDK 5](java-library-install_5.md)
+ [Supported key types for JCE provider for AWS CloudHSM Client SDK 5](java-lib-keys_5.md)
+ [Key management basics in the JCE provider for AWS CloudHSM Client SDK 5](java-library-key-basics_5.md)
+ [Supported mechanisms for JCE provider for AWS CloudHSM Client SDK 5](java-lib-supported_5.md)
+ [Supported Java key attributes for AWS CloudHSM Client SDK 5](java-lib-attributes_5.md)
+ [Code samples for the AWS CloudHSM software library for Java for Client SDK 5](java-samples.md)
+ [AWS CloudHSM JCE provider Javadocs](java-javadocs_5.md)
+ [AWS CloudHSM KeyStore Java class for Client SDK 5](alternative-keystore_5.md)
+ [Advanced configurations for AWS CloudHSM JCE for Client SDK 5](java-lib-configs.md)
# Install the JCE provider for AWS CloudHSM Client SDK 5
The JCE provider for AWS CloudHSM Client SDK 5 is compatible with OpenJDK 8, OpenJDK 11, OpenJDK 17, OpenJDK 21, and OpenJDK 25. You can download both from the [OpenJDK website](https://openjdk.java.net/).
Use the following sections to install and provide credentials to the provider.
**Note**
To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting `disable_key_availability_check` to `True`. For more information, see [Key Synchronization](manage-key-sync.md) and [Client SDK 5 Configure Tool](configure-sdk-5.md).
**Topics**
+ [Step 1: Install the JCE provider](#install-java-library_5)
+ [Step 2: Provide credentials to the JCE provider](#java-library-credentials_5)
## Step 1: Install the JCE provider
1. Use the following commands to download and install the JCE provider.
------
#### [ Amazon Linux 2023 ]
Install the JCE provider for Amazon Linux 2023 on x86\$164 architecture:
```
$ 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
```
Install the JCE provider for Amazon Linux 2023 on ARM64 architecture:
```
$ 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 ]
Install the JCE provider for Amazon Linux 2 on x86\$164 architecture:
```
$ 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
```
Install the JCE provider for Amazon Linux 2 on ARM64 architecture:
```
$ 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) ]
Install the JCE provider for RHEL 10 on x86\$164 architecture:
```
$ 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
```
Install the JCE provider for RHEL 10 on ARM64 architecture:
```
$ 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) ]
Install the JCE provider for RHEL 9 (9.2\$1) on x86\$164 architecture:
```
$ 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
```
Install the JCE provider for RHEL 9 (9.2\$1) on ARM64 architecture:
```
$ 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) ]
Install the JCE provider for RHEL 8 on x86\$164 architecture:
```
$ 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
```
Install the JCE provider for RHEL 8 on ARM64 architecture:
```
$ 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 ]
Install the JCE provider for Ubuntu 24.04 LTS on x86\$164 architecture:
```
$ 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
```
Install the JCE provider for Ubuntu 24.04 LTS on ARM64 architecture:
```
$ 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 ]
Install the JCE provider for Ubuntu 22.04 LTS on x86\$164 architecture:
```
$ 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
```
Install the JCE provider for Ubuntu 22.04 LTS on ARM64 architecture:
```
$ 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 ]
Install the JCE provider for Windows Server on x86\$164 architecture, open PowerShell as an administrator and run the following command:
```
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. Bootstrap Client SDK 5. For more information about bootstrapping, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. Locate the following JCE provider files:
------
#### [ 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`
------
## Step 2: Provide credentials to the JCE provider
Before your Java application can use an HSM, the HSM needs to first authenticate the application. HSMs authenticate using either an explicit login or implicit login method.
**Explicit login** – This method lets you provide AWS CloudHSM credentials directly in the application. It uses the method from the [https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html](https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html), where you pass a CU username and password in the pin pattern. For more information, see [Login to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java) code example.
**Implicit login** – This method lets you set AWS CloudHSM credentials either in a new property file, system properties, or as environment variables.
+ **System properties** – Set credentials through system properties when running your application. The following examples show two different ways that you can do this:
------
#### [ 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","");
```
------
+ **Environment variables** – Set credentials as environment variables.
**Note**
When setting environment variables, you must escape any special characters that may be interpreted by your shell.
------
#### [ Linux ]
```
$ export HSM_USER=
$ export HSM_PASSWORD=
```
------
#### [ Windows ]
```
PS C:\> $Env:HSM_USER=""
PS C:\> $Env:HSM_PASSWORD=""
```
------
Credentials might not be available if the application does not provide them or if you attempt an operation before the HSM authenticates session. In those cases, the CloudHSM software library for Java searches for the credentials in the following order:
1. System properties
1. Environment variables
# Supported key types for JCE provider for AWS CloudHSM Client SDK 5
The AWS CloudHSM software library for Java enables you to generate the following key types.
****
| Key Type | Description |
| --- | --- |
| AES | Generate 128, 192, and 256-bit AES keys. |
| Triple DES (3DES, DESede) | Generate a 192-bit Triple DES Key [*](#java-lib-keys_5-note-1). |
| EC | Generate EC key pairs – NIST curves secp224r1 (P-224), secp256r1 (P-256), secp256k1 (Blockchain), secp384r1 (P-384), and secp521r1 (P-521). |
| GENERIC\$1SECRET | Generate 1 to 800 bytes generic secrets. |
| HMAC | Hash support for SHA1, SHA224, SHA256, SHA384, SHA512. |
| RSA | Generate 2048-bit to 4096-bit RSA keys, in increments of 256 bits. |
\$1 In accordance with NIST guidance, this is disallowed for clusters in FIPS mode after 2023. For clusters in non-FIPS mode, it is still allowed after 2023. See [FIPS 140 Compliance: 2024 Mechanism Deprecation](compliance-dep-notif.md#compliance-dep-notif-1) for details.
# Key management basics in the JCE provider for AWS CloudHSM Client SDK 5
The basics on key management in the JCE provider involve importing keys, exporting keys, loading keys by handle, or deleting keys. For more information on managing keys, see the [Manage keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java) code example.
You can also find more JCE provider code examples at [Code samples](java-samples.md).
# Supported mechanisms for JCE provider for AWS CloudHSM Client SDK 5
This topic provides information about supported mechanisms for JCE provider with AWS CloudHSM Client SDK 5. For information about the Java Cryptography Architecture (JCA) interfaces and engine classes supported by AWS CloudHSM, see the following topics.
**Topics**
+ [Generate key and key pair functions](#java-gen-key-pairs-5)
+ [Cipher functions](#java-ciphers_5)
+ [Sign and verify functions](#java-sign-verify_5)
+ [Digest functions](#java-digests_5)
+ [Hash-based message authentication code (HMAC) functions](#java-mac_5)
+ [Cipher-based message authentication code (CMAC) functions](#java-cmac_5)
+ [Key Agreement Functions](#java-key-derivation_5)
+ [Convert keys to key specifications using key factories](#java-key-factories)
+ [Mechanism annotations](#w2aac25c21c25c15c23)
## Generate key and key pair functions
The AWS CloudHSM software library for Java allows you to use the following operations for generate key and key pair functions.
+ `RSA`
+ `EC`
+ `AES`
+ `DESede (Triple DES)`see note [1](#java-gen-key-pairs-5-note-1)
+ `GenericSecret`
## Cipher functions
The AWS CloudHSM software library for Java supports the following algorithm, mode, and padding combinations.
| Algorithm | Mode | Padding | Notes |
| --- | --- | --- | --- |
| AES | CBC | `AES/CBC/NoPadding` `AES/CBC/PKCS5Padding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. Implements `Cipher.UNWRAP_MODE for AES/CBC NoPadding` |
| AES | ECB | `AES/ECB/PKCS5Padding` `AES/ECB/NoPadding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. |
| AES | CTR | `AES/CTR/NoPadding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. |
| AES | GCM | `AES/GCM/NoPadding` | Implements `Cipher.WRAP_MODE`, `Cipher.UNWRAP_MODE`, `Cipher.ENCRYPT_MODE`, and `Cipher.DECRYPT_MODE`.When performing AES-GCM encryption, the HSM ignores the initialization vector (IV) in the request and uses an IV that it generates. When the operation completes, you must call `Cipher.getIV()` to get the IV. |
| AESWrap | ECB | `AESWrap/ECB/NoPadding` `AESWrap/ECB/PKCS5Padding` `AESWrap/ECB/ZeroPadding` | Implements `Cipher.WRAP_MODE` and `Cipher.UNWRAP_MODE`. |
| DESede (Triple DES) | CBC | `DESede/CBC/PKCS5Padding` `DESede/CBC/NoPadding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. See note [1](#java-gen-key-pairs-5-note-1) below for an upcoming change. |
| DESede (Triple DES) | ECB | `DESede/ECB/NoPadding` `DESede/ECB/PKCS5Padding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. See note [1](#java-gen-key-pairs-5-note-1) below for an upcoming change. |
| RSA | ECB | `RSA/ECB/PKCS1Padding` **see note [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` | Implements `Cipher.WRAP_MODE`, `Cipher.UNWRAP_MODE`, `Cipher.ENCRYPT_MODE`, and `Cipher.DECRYPT_MODE`. |
| RSA | ECB | `RSA/ECB/NoPadding` | Implements `Cipher.ENCRYPT_MODE` and `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` | Implements `Cipher.WRAP_MODE` and `Cipher.UNWRAP_MODE`. |
## Sign and verify functions
The AWS CloudHSM software library for Java supports the following types of signature and verification. With Client SDK 5 and signature algorithms with hashing, the data is hashed locally in software before being sent to the HSM for the signature/verification. This means there is no limit on the size of the data that can be hashed by the SDK.
**RSA Signature Types**
+ `NONEwithRSA`
+ `RSASSA-PSS`
+ `SHA1withRSA`
+ `SHA1withRSA/PSS`
+ `SHA1withRSAandMGF1`
+ `SHA224withRSA`
+ `SHA224withRSAandMGF1`
+ `SHA224withRSA/PSS`
+ `SHA256withRSA`
+ `SHA256withRSAandMGF1`
+ `SHA256withRSA/PSS`
+ `SHA384withRSA`
+ `SHA384withRSAandMGF1`
+ `SHA384withRSA/PSS`
+ `SHA512withRSA`
+ `SHA512withRSAandMGF1`
+ `SHA512withRSA/PSS`
**ECDSA Signature Types**
+ `NONEwithECDSA`
+ `SHA1withECDSA`
+ `SHA224withECDSA`
+ `SHA256withECDSA`
+ `SHA384withECDSA`
+ `SHA512withECDSA`
## Digest functions
The AWS CloudHSM software library for Java supports the following message digests. With Client SDK 5, the data is hashed locally in software. This means there is no limit on the size of the data that can be hashed by the SDK.
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
## Hash-based message authentication code (HMAC) functions
The AWS CloudHSM software library for Java supports the following HMAC algorithms.
+ `HmacSHA1` (Maximum data size in bytes: 16288)
+ `HmacSHA224` (Maximum data size in bytes: 16256)
+ `HmacSHA256` (Maximum data size in bytes: 16288)
+ `HmacSHA384` (Maximum data size in bytes: 16224)
+ `HmacSHA512` (Maximum data size in bytes: 16224)
## Cipher-based message authentication code (CMAC) functions
CMACs (Cipher-based message authentication codes) create message authentication codes (MACs) using a block cipher and a secret key. They differ from HMACs in that they use a block symmetric key method for the MACs rather than a hashing method.
The AWS CloudHSM software library for Java supports the following CMAC algorithms.
+ `AESCMAC`
## Key Agreement Functions
The AWS CloudHSM software library for Java supports ECDH with Key Derivation Functions (KDF). The following KDF types are supported:
+ `ECDHwithX963SHA1KDF` Supports X9.63 KDF SHA1 algorithm[2](#kdf2)
+ `ECDHwithX963SHA224KDF` Supports X9.63 KDF SHA224 algorithm[2](#kdf2)
+ `ECDHwithX963SHA256KDF` Supports X9.63 KDF SHA256 algorithm[2](#kdf2)
+ `ECDHwithX963SHA384KDF` Supports X9.63 KDF SHA384 algorithm[2](#kdf2)
+ `ECDHwithX963SHA512KDF` Supports X9.63 KDF SHA512 algorithm[2](#kdf2)
## Convert keys to key specifications using key factories
You can use key factories to convert keys to key specifications. AWS CloudHSM has two types of key factories for JCE:
**SecretKeyFactory:** Used to import or derive symmetric keys. Using SecretKeyFactory, you can pass a supported Key or a supported KeySpec to import or derive symmetric keys into AWS CloudHSM. Following are the supported specs for KeyFactory:
+ For SecretKeyFactory's `generateSecret` method following [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) classes are supported:
+ **KeyAttributesMap**can be used to import a key bytes with additional attributes as a CloudHSM Key. An example can be found here [here](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)**can be used to import a symmetric key spec as a CloudHSM Key.
+ **AesCmacKdfParameterSpec**can be used to derive symmetric keys using another CloudHSM AES Key.
**Note**
SecretKeyFactory's `translateKey` method takes any key that implements the [key](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html) interface.
**KeyFactory:** Used for importing asymmetric keys. Using KeyFactory, you can pass a supported Key or supported KeySpec to import an asymmetric key into AWS CloudHSM. For more information, refer to the following resources:
+ For KeyFactory's `generatePublic` method, following [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) classes are supported:
+ CloudHSM KeyAttributesMap for both RSA and EC KeyTypes, including:
+ CloudHSM KeyAttributesMap for both RSA and EC public KeyTypes. An example can be found [here](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [X509EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/X509EncodedKeySpec.html) for both RSA and EC Public Key
+ [RSAPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPublicKeySpec.html) for RSA Public Key
+ [ECPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPublicKeySpec.html) for EC Public Key
+ For KeyFactory's `generatePrivate` method, following [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) classes are supported:
+ CloudHSM KeyAttributesMap for both RSA and EC KeyTypes, including:
+ CloudHSM KeyAttributesMap for both RSA and EC public KeyTypes. An example can be found [here](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) for both EC and RSA Private Key
+ [RSAPrivateCrtKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPrivateCrtKeySpec.html) for RSA Private Key
+ [ECPrivateKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPrivateKeySpec.html) for EC Private Key
For KeyFactory's `translateKey` method, it takes in any Key that implements the [Key Interface](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html).
## Mechanism annotations
[1] In accordance with NIST guidance, this is disallowed for clusters in FIPS mode after 2023. For clusters in non-FIPS mode, it is still allowed after 2023. See [FIPS 140 Compliance: 2024 Mechanism Deprecation](compliance-dep-notif.md#compliance-dep-notif-1) for details.
[2] Key derivation functions (KDFs) are specified in [NIST Special Publication 800-56A Revision 3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf).
# Supported Java key attributes for AWS CloudHSM Client SDK 5
This topic provides information about supported Java key attributes for AWS CloudHSM Client SDK 5. This topic describes how to use a proprietary extension for the JCE provider to set key attributes. Use this extension to set supported key attributes and their values during these operations:
+ Key generation
+ Key import
For examples of how to use key attributes, see [Code samples for the AWS CloudHSM software library for Java for Client SDK 5](java-samples.md).
**Topics**
+ [Understanding attributes](#java-understanding-attributes_5)
+ [Supported attributes](#java-attributes_5)
+ [Setting attributes for a key](#java-setting-attributes_5)
## Understanding attributes
Use key attributes to specify what actions are permitted on key objects, including public, private or secret keys. Key attributes and values are defined during key object creation operations.
The Java Cryptography Extension (JCE) does not specify how you should set values on key attributes, so most actions were permitted by default. In contrast, the PKCS\$1 11 standard defines a comprehensive set of attributes with more restrictive defaults. Starting with the JCE provider 3.1, AWS CloudHSM provides a proprietary extension that enables you to set more restrictive values for commonly used attributes.
## Supported attributes
You can set values for the attributes listed in the following table. As a best practice, only set values for attributes you wish to make restrictive. If you don’t specify a value, AWS CloudHSM uses the default value specified in the table below. An empty cell in the Default Value columns indicates that there is no specific default value assigned to the attribute.
****
| Attribute | Default Value | Notes | | Symmetric Key | Public Key in Key Pair | Private Key in Key Pair | |
| --- | --- | --- | --- | --- | --- | --- | --- |
| DECRYPT | TRUE | | TRUE | True indicates you can use the key to decrypt any buffer. You generally set this to FALSE for a key whose WRAP is set to true. |
| DERIVE | | | | Allows a key to be used to derive other keys. |
| ENCRYPT | TRUE | TRUE | | True indicates you can use the key to encrypt any buffer. |
| EXTRACTABLE | TRUE | | TRUE | True indicates you can export this key out of the HSM. |
| ID | | | | A user-defined value used to identify the key. |
| KEY\$1TYPE | | | | Used to identify the type of key (AES, DESede, generic secret, EC, or RSA). |
| LABEL | | | | A user-defined string allowing you to conveniently identify keys on your HSM. To follow best practice, use a unique label for each key so it is easier to find later. |
| LOCAL | | | | Indicates a key generated by the HSM. |
| OBJECT\$1CLASS | | | | Used to identify the Object Class of a key (SecretKey, PublicKey or PrivateKey). |
| PRIVATE | TRUE | TRUE | TRUE | True indicates that a user may not access the key until the user is authenticated. For clarity, users cannot access any keys on AWS CloudHSM until they are authenticated, even if this attribute is set to FALSE. |
| SIGN | TRUE | | TRUE | True indicates you can use the key to sign a message digest. This is generally set to FALSE for public keys and for private keys that you have archived. |
| SIZE | | | | An attribute that defines the size of a key. For more details about supported key sizes, refer to [Supported mechanisms for Client SDK 5](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-lib-supported_5.html#java-keys_5). |
| TOKEN | FALSE | FALSE | FALSE | A permanent key which is replicated across all HSMs in the cluster and included in backups. TOKEN = FALSE implies an ephemeral key which is automatically erased when the connection to the HSM is broken or logged out. |
| UNWRAP | TRUE | | TRUE | True indicates you can use the key to unwrap (import) another key. |
| VERIFY | TRUE | TRUE | | True indicates you can use the key to verify a signature. This is generally set to FALSE for private keys. |
| WRAP | TRUE | TRUE | | True indicates you can use the key to wrap another key. You will generally set this to FALSE for private keys. |
| WRAP\$1WITH\$1TRUSTED | FALSE | | FALSE | True indicates a key can only be wrapped and unwrapped with keys that have the TRUSTED attribute set to true. Once a key has WRAP\$1WITH\$1TRUSTED set to true, that attribute is read-only and can’t be set to false. To read about trust wrapping, see [Using trusted keys to control key unwraps](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_using_trusted_keys_control_key_wrap.html). |
**Note**
You get broader support for attributes in the PKCS\$111 library. For more information, see [Supported PKCS \$111 Attributes](pkcs11-attributes.md).
## Setting attributes for a key
`KeyAttributesMap` is a Java Map-like object, which you can use to set attribute values for key objects. The methods for `KeyAttributesMap` function similar to the methods used for Java map manipulation.
To set custom values on attributes, you have two options:
+ Use the methods listed in the following table
+ Use builder patterns demonstrated later in this document
Attribute map objects support the following methods to set attributes:
****
| Operation | Return Value | `KeyAttributesMap` method |
| --- | --- | --- |
| Get the value of a key attribute for an existing key | Object (containing the value) or null | **get**(keyAttribute) |
| Populate the value of one key attribute | The previous value associated with key attribute, or null if there was no mapping for a key attribute | **put**(keyAttribute, value) |
| Populate values for multiple key attributes | N/A | **putAll**(keyAttributesMap) |
| Remove a key-value pair from the attribute map | The previous value associated with key attribute, or *null* if there was no mapping for a key attribute | **remove**(keyAttribute) |
**Note**
Any attributes you do not explicitly specify are set to the defaults listed in the preceding table in [Supported attributes](#java-attributes_5).
### Setting attributes for a key pair
Use the Java class `KeyPairAttributesMap` to handle key attributes for a key pair. `KeyPairAttributesMap` encapsulates two `KeyAttributesMap` objects; one for a public key and one for a private key.
To set individual attributes for the public key and private key separately, you can use the `put()` method on corresponding `KeyAttributes` map object for that key. Use the `getPublic()` method to retrieve the attribute map for the public key, and use `getPrivate()` to retrieve the attribute map for the private key. Populate the value of multiple key attributes together for both public and private key pairs using the `putAll()` with a key pair attributes map as its argument.
# Code samples for the AWS CloudHSM software library for Java for Client SDK 5
This topic provides resources and information on Java code samples for AWS CloudHSM Client SDK 5.
## Prerequisites
Before running the samples, you must set up your environment:
+ Install and configure the [Java Cryptographic Extension (JCE) provider](java-library-install_5.md#install-java-library_5).
+ Set up a valid [HSM user name and password](manage-hsm-users.md). Cryptographic user (CU) permissions are sufficient for these tasks. Your application uses these credentials to log in to the HSM in each example.
+ Decide how to provide credentials to the [JCE provider](java-library-install_5.md#java-library-credentials_5).
## Code samples
The following code samples show you how to use the [AWS CloudHSM JCE provider](java-library.md) to perform basic tasks. More code samples are available on [GitHub](https://github.com/aws-samples/aws-cloudhsm-jce-examples/tree/sdk5).
+ [Log in to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)
+ [Manage keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [Generate Symmetric Keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)
+ [Generate Asymmetric Keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java)
+ [Encrypt and decrypt with AES-GCM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java)
+ [Encrypt and decrypt with AES-CTR](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java)
+ [Encrypt and decrypt with DESede-ECB](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java)see note [1](#java-samples-code-5-note-1)
+ [Sign and Verify with RSA Keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/RSAOperationsRunner.java)
+ [Sign and Verify with EC Keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.java)
+ [Use supported key attributes](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyAttributesRunner.java)
+ [Use the CloudHSM key store](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.java)
[1] In accordance with NIST guidance, this is disallowed for clusters in FIPS mode after 2023. For clusters in non-FIPS mode, it is still allowed after 2023. See [FIPS 140 Compliance: 2024 Mechanism Deprecation](compliance-dep-notif.md#compliance-dep-notif-1) for details.
# AWS CloudHSM JCE provider Javadocs
Use the JCE provider Javadocs to get usage information on Java types and methods defined in the AWS CloudHSM JCE SDK. To download the latest Javadocs for AWS CloudHSM, see the [AWS CloudHSM latest Client SDK release](latest-releases.md) section on the Downloads page.
You can import Javadocs into an integrated development environment (IDE) or view them in a web browser.
# AWS CloudHSM KeyStore Java class for Client SDK 5
The AWS CloudHSM `KeyStore` class provides a special-purpose PKCS12 key store. This key store can store certificates along with your key data and correlate them to key data stored on AWS CloudHSM. The AWS CloudHSM `KeyStore` class implements the `KeyStore` Service Provider Interface (SPI) of the Java Cryptography Extension (JCE). For more information about using `KeyStore`, see [Class KeyStore](https://devdocs.io/openjdk~8/java/security/keystore).
**Note**
Because certificates are public information, and to maximize storage capacity for cryptographic keys, AWS CloudHSM does not support storing certificates on HSMs.
## Choose the appropriate key store for AWS CloudHSM Client SDK 5
The AWS CloudHSM Java Cryptographic Extension (JCE) provider offers a special-purpose AWS CloudHSM KeyStore. The AWS CloudHSM `KeyStore` class supports offloading key operations to the HSM, local storage of certificates and certificate-based operations.
Load the special-purpose CloudHSM KeyStore as follows:
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## Initialize the AWS CloudHSM KeyStore Client SDK 5
Log into the AWS CloudHSM KeyStore the same way that you log into the JCE provider. You can use either environment variables or the system property file, and you should log in before you start using the CloudHSM KeyStore. For an example of logging into an HSM using the JCE provider, see [Login to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java).
If desired, you can specify a password to encrypt the local PKCS12 file which holds key store data. When you create the AWS CloudHSM Keystore, you set the password and provide it when using the load, set and get methods.
Instantiate a new CloudHSM KeyStore object as follows:
```
ks.load(null, null);
```
Write keystore data to a file using the `store` method. From that point on, you can load the existing keystore using the `load` method with the source file and password as follows:
```
ks.load(inputStream, password);
```
## Use AWS CloudHSM KeyStore or AWS CloudHSM Client SDK 5
AWS CloudHSM KeyStore complies with the JCE [Class KeyStore](https://devdocs.io/openjdk~8/java/security/keystore) specification and provides the following functions.
+ `load`
Loads the key store from the given input stream. If a password was set when saving the key store, this same password must be provided for the load to succeed. Set both parameters to null to initialize an new empty key store.
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
ks.load(inputStream, password);
```
+ `aliases`
Returns an enumeration of the alias names of all entries in the given key store instance. Results include objects stored locally in the PKCS12 file and objects resident on the HSM.
**Sample code:**
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
for(Enumeration entry = ks.aliases(); entry.hasMoreElements();) {
String label = entry.nextElement();
System.out.println(label);
}
```
+ `containsalias`
Returns true if the key store has access to at least one object with the specified alias. The key store checks objects stored locally in the PKCS12 file and objects resident on the HSM.
+ `deleteEntry`
Deletes a certificate entry from the local PKCS12 file. Deleting key data stored in an HSM is not supported using the AWS CloudHSM KeyStore. You can delete keys using the `destroy` method of the [Destroyable](https://devdocs.io/openjdk~8/javax/security/auth/destroyable#destroy--) interface.
```
((Destroyable) key).destroy();
```
+ `getCertificate`
Returns the certificate associated with an alias if available. If the alias does not exist or references an object which is not a certificate, the function returns NULL.
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
Certificate cert = ks.getCertificate(alias);
```
+ `getCertificateAlias`
Returns the name (alias) of the first key store entry whose data matches the given certificate.
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
String alias = ks.getCertificateAlias(cert);
```
+ `getCertificateChain`
Returns the certificate chain associated with the given alias. If the alias does not exist or references an object which is not a certificate, the function returns NULL.
+ `getCreationDate`
Returns the creation date of the entry identified by the given alias. If a creation date is not available, the function returns the date on which the certificate became valid.
+ `getKey`
GetKey is passed to the HSM and returns a key object corresponding to the given label. As `getKey` directly queries the HSM, it can be used for any key on the HSM regardless of whether it was generated by the KeyStore.
```
Key key = ks.getKey(keyLabel, null);
```
+ `isCertificateEntry`
Checks if the entry with the given alias represents a certificate entry.
+ `isKeyEntry`
Checks if the entry with the given alias represents a key entry. The action searches both the PKCS12 file and the HSM for the alias.
+ `setCertificateEntry`
Assigns the given certificate to the given alias. If the given alias is already being used to identify a key or certificate, a `KeyStoreException` is thrown. You can use JCE code to get the key object and then use the KeyStore `SetKeyEntry` method to associate the certificate to the key.
+ `setKeyEntry` with `byte[]` key
**This API is currently unsupported with Client SDK 5.**
+ `setKeyEntry` with `Key` object
Assigns the given key to the given alias and stores it inside the HSM. If the key does not already exist inside the HSM, it will be imported into the HSM as an extractable session key.
If the `Key` object is of type `PrivateKey`, it must be accompanied by a corresponding certificate chain.
If the alias already exists, the `SetKeyEntry` call throws a `KeyStoreException` and prevents the key from being overwritten. If the key must be overwritten, use KMU or JCE for that purpose.
+ `engineSize`
Returns the number of entries in the keystore.
+ `store`
Stores the key store to the given output stream as a PKCS12 file and secures it with the given password. In addition, it persists all loaded keys (which are set using `setKey` calls).
# Advanced configurations for AWS CloudHSM JCE for Client SDK 5
The AWS CloudHSM JCE provider includes the following advanced configurations, which are not part of the general configurations most customers utilize.
+ [Connecting to multiple clusters](java-lib-configs-multi.md)
+ [Key extraction using JCE](java-lib-configs-getencoded.md)
+ [Retry configuration for JCE](java-lib-configs-retry.md)
# Connecting to multiple AWS CloudHSM clusters with the JCE provider
This configuration allows a single client instance to communicate to multiple AWS CloudHSM clusters. Compared to having a single instance only communicate with a single cluster, this can be a cost-savings feature for some use cases. The `CloudHsmProvider` class is AWS CloudHSM's implementation of [Java Security's Provider class](https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html). Each instance of this class represents a connection to your entire AWS CloudHSM cluster. You instantiate this class and add it to Java Security provider's list so that you can interact with it using standard JCE classes.
The following example instantiates this class and adds it to Java Security provider’s list:
```
if (Security.getProvider(CloudHsmProvider.PROVIDER_NAME) == null) {
Security.addProvider(new CloudHsmProvider());
}
```
`CloudHsmProvider` can be configured in two ways:
1. Configure with file (default configuration)
1. Configure using code
The following topics describe these configurations, and how to connect to multiple clusters.
**Topics**
+ [Configure the AWS CloudHSM `CloudHsmProvider` class with a file (Default configuration)](java-lib-configs-default.md)
+ [Configure the AWS CloudHSM `CloudHsmProvider` class using code](java-lib-configs-using-code.md)
+ [Connect to multiple AWS CloudHSM clusters](java-lib-connecting-to-multiclusters.md)
# Configure the AWS CloudHSM `CloudHsmProvider` class with a file (Default configuration)
The default way to configure the AWS CloudHSM `CloudHsmProvider` class is with a file.
When you instantiate `CloudHsmProvider` using default constructor, by default it will look for configuration file in `/opt/cloudhsm/etc/cloudhsm-jce.cfg` path in Linux. This configuration file can be configured using the `configure-jce`.
An object created using the default constructor will use the default CloudHSM provider name `CloudHSM`. The provider name is useful to interact with JCE to let it know which provider to use for various operation. An example to use CloudHSM provider name for Cipher operation is as below:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHSM");
```
# Configure the AWS CloudHSM `CloudHsmProvider` class using code
As of Client SDK version 5.8.0, you can also configure the AWS CloudHSM `CloudHsmProvider` class using Java code. The way to do this is using an object of `CloudHsmProviderConfig` class. You can build this object using `CloudHsmProviderConfigBuilder`.
`CloudHsmProvider` has another constructor which takes the `CloudHsmProviderConfig` object, as the following sample shows.
**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);
```
In this example, the name of the JCE provider is `CloudHsmCluster1`. This is the name that application can then use to interact with JCE:
**Example**
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHsmCluster1");
```
Alternatively, applications can also use the provider object created above to let JCE know to use that provider for the operation:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider);
```
If a unique identifier is not specified with the `withClusterUniqueIdentifier` method, a randomly generated provider name is created for you. To get this randomly generated identifier, applications can call `provider.getName()` to get the identifier.
# Connect to multiple AWS CloudHSM clusters
Each `CloudHsmProvider` represents a connection to your AWS CloudHSM Cluster. If you want to talk to another cluster from the same application, you can create another object of `CloudHsmProvider` with configurations for your other cluster and you can interact with this other cluster either using the provider object or using the provider name, as shown in the following example.
**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);
}
```
Once you have configured both the providers (both the clusters) above, you can interact with them either using the provider object or using the provider name.
Expanding upon this example that shows how to talk to `cluster1`, you could use the following sample for a AES/GCM/NoPadding operation:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider1);
```
And in the same application to do "AES" Key generation on the second cluster using the provider name, you could also use the following sample:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider2.getName());
```
# Key extraction using JCE for AWS CloudHSM
The Java Cryptography Extension (JCE) uses an architecture that allows different cryptography implementations to be plugged in. AWS CloudHSM ships one such JCE provider that offloads cryptographic operations to the HSM. For most other JCE providers to work with keys stored in AWS CloudHSM, they must extract the key bytes from your HSMs in clear text into your machine’s memory for their use. HSMs typically only allow keys to be extracted as wrapped objects, not clear text. However, to support inter-provider integration use cases, AWS CloudHSM allows an opt-in configuration option to enable extraction of the key bytes in the clear.
**Important**
JCE offloads operations to AWS CloudHSM whenever the AWS CloudHSM provider is specified or an AWS CloudHSM key object is used. You do not need to extract keys in clear if you expect your operation to happen inside the HSM. Key extraction in clear text is only needed when your application cannot use secure mechanisms such as wrapping and unwrapping a key due to restrictions from a third party library or JCE provider.
The AWS CloudHSM JCE Provider allows extraction of **public keys** to work with external JCE providers by default. The following methods are always allowed:
| Class | Method | Format (getEncoded) |
| --- | --- | --- |
| EcPublicKey | getEncoded() | X.509 |
| | getW() | N/A |
| RSAPublicKey | getEncoded() | X.509 |
| | getPublicExponent() | N/A |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | N/A |
The AWS CloudHSM JCE Provider doesn’t allow extraction of key bytes in clear for the **private** or **secret** keys by default. If your use case requires it, you can enable extraction of key bytes in clear for **private** or **secret** keys under the following conditions:
1. The `EXTRACTABLE` attribute for private and secret keys is set to **true**.
+ By default, the `EXTRACTABLE` attribute for private and secret keys is set to **true**. `EXTRACTABLE` keys are keys that are permitted to be exported out of the HSM. For more information see Supported Java attributes for [Client SDK 5](java-lib-attributes_5.md).
1. The `WRAP_WITH_TRUSTED` attribute for the private and secret keys is set to **false**.
+ `getEncoded`, `getPrivateExponent`, and `getS` cannot be used with private keys that cannot be exported in clear. `WRAP_WITH_TRUSTED` doesn't allow your private keys to exported out of the HSM in clear. For more information see [Using trusted keys to control key unwraps](manage-keys-using-trusted-keys.md).
# Allow the JCE provider to extract private key secrets out of AWS CloudHSM
Use the following steps to allow AWS CloudHSM JCE provider to extract your private key secrets.
**Important**
This configuration change allows extraction of all `EXTRACTABLE` key bytes in clear from your HSM cluster. For better security, you should consider using [key wrapping methods](java-lib-supported_5.md) to extract the key out of the HSM securely. This prevents unintentional extraction of your key bytes from the HSM.
1. Use the following commands to enable your **private** or **secret** keys to be extracted in 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. Once you enable your clear key extraction, the following methods are enabled for extracting private keys into memory.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/get-encoded-take-out-private-keys.html)
If you want restore the default behavior and not allow JCE to export keys in clear, run the following command:
------
#### [ 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
```
------
# Retry commands for JCE for AWS CloudHSM
AWS CloudHSM Client SDK 5.8.0 and later have a built-in automatic retry strategy which will retry HSM-throttled operations from the client side. When an HSM throttles operations because it is too busy performing previous operations and cannot take more requests, client SDKs will attempt to retry throttled operations up to 3 times while exponentially backing off. This automatic retry strategy can be set to one of two modes: **off** and **standard**.
+ **off**: The Client SDK will not perform any retry strategy for any throttled operations by the HSM.
+ **standard**: This is the default mode for Client SDK 5.8.0 and later. In this mode, client SDKs will automatically retry throttled operations by exponentially backing off.
For more information, see [HSM throttling](troubleshoot-hsm-throttling.md).
## Set retry commands to off mode
------
#### [ Linux ]
**To set retry commands to **off** for Client SDK 5 on Linux**
+ You can use the following command to set retry configuration to **off** mode:
```
$ sudo /opt/cloudhsm/bin/configure-jce --default-retry-mode off
```
------
#### [ Windows ]
**To set retry commands to **off** for Client SDK 5 on Windows**
+ You can use the following command to set retry configuration to **off** mode:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --default-retry-mode off
```
------