# Offload operations with AWS CloudHSM Client SDKs
Use a Client SDK to offload cryptographic operations from platform or language-based applications to hardware security modules (HSMs).
AWS CloudHSM offers two major versions, and Client SDK 5 is the latest. It offers a variety of advantages over Client SDK 3 (the previous series). For more information, see [ Benefits of Client SDK 5](client-sdk-5-benefits.md). For information about platform support, see [AWS CloudHSM Client SDK 5 supported platforms](client-supported-platforms.md).
The following topics describe how to work with AWS CloudHSM Client SDKs.
AWS CloudHSM supports the following components:
**[PKCS \$111 library for AWS CloudHSM Client SDK 5](pkcs11-library.md)**
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.
**[OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl-library.md)**
The AWS CloudHSM OpenSSL Dynamic Engine allows you to offload cryptographic operations to your CloudHSM cluster through the OpenSSL API.
**[OpenSSL Provider for AWS CloudHSM Client SDK 5](openssl-provider-library.md)**
The AWS CloudHSM OpenSSL Dynamic Engine Provider allows you to offload cryptographic operations to your CloudHSM cluster through the OpenSSL Provider API.
**[JCE provider for AWS CloudHSM Client SDK 5](java-library.md)**
The AWS CloudHSM JCE provider is compliant with the Java Cryptographic Architecture (JCA). The provider allows you to perform cryptographic operations on the HSM.
**[Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library.md)**
The AWS CloudHSM client for Windows includes CNG and KSP providers.
**Topics**
+ [Check your AWS CloudHSM Client SDK version](check-client_version.md)
+ [Compare AWS CloudHSM Client SDK component support](sdk3-compare.md)
+ [Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5](client-sdk-migration.md)
+ [Using Client SDK 5 to work with AWS CloudHSM](client-sdk5.md)
+ [Using previous SDK version to work with AWS CloudHSM](choose-client-sdk.md)
# Check your AWS CloudHSM Client SDK version
Use the following commands to verify the version of Client SDK that you're using with AWS CloudHSM.
------
#### [ Amazon Linux ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ Amazon Linux 2 ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ CentOS 6 ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ CentOS 7 ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ CentOS 8 ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ RHEL 6 ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ RHEL 7 ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ RHEL 8 ]
Use the following command:
```
rpm -qa | grep ^cloudhsm
```
------
#### [ Ubuntu 16.04 LTS ]
Use the following command:
```
apt list --installed | grep ^cloudhsm
```
------
#### [ Ubuntu 18.04 LTS ]
Use the following command:
```
apt list --installed | grep ^cloudhsm
```
------
#### [ Ubuntu 20.04 LTS ]
Use the following command:
```
apt list --installed | grep ^cloudhsm
```
------
#### [ Windows Server ]
Use the following command:
```
wmic product get name,version
```
------
# Compare AWS CloudHSM Client SDK component support
In addition to the command-line tools, Client SDK 3 contains components that enable off-loading cryptographic operations to the HSM from various platform or language-based applications. Client SDK 5 has parity with Client SDK 3, except it does not yet support CNG and KSP providers. The following table compares component availability in Client SDK 3 and Client SDK 5.
| Component | Client SDK 5 | Client SDK 3 |
| --- | --- | --- |
| PKCS \$111 library | Yes | Yes |
| JCE provider | Yes | Yes |
| OpenSSL Dynamic Engine | Yes | Yes |
| Key Storage Provider (KSP) | Yes | Yes |
| CloudHSM Management Utility (CMU)[1](#sdk-compare-note-1) | Yes | Yes |
| Key Management Utility (KMU)[1](#sdk-compare-note-1) | Yes | Yes |
| Configure tool | Yes | Yes |
[1] CMU and KMU components are included in CloudHSM CLI with Client SDK 5.
The following sections describe the components.
## PKCS \$111 library
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 Client SDK 3, the PKCS \$111 library is a Linux only component that matches Linux base support. For more information, see [Linux support for AWS CloudHSM Client SDK 3](sdk3-linux.md).
+ For Client SDK 5, the PKCS \$111 library is a cross-platform component that matches Linux and Windows Client SDK 5 base support. For more information, see [Linux support for AWS CloudHSM Client SDK 5](sdk8-linux.md) and [Windows support for AWS CloudHSM Client SDK 5](sdk8-windows.md).
## CloudHSM Management Utility (CMU)
The CloudHSM Management Utility (CMU) command line tool helps crypto officers manage users in the HSMs. It includes tools that create, delete, and list users, and change user passwords. For more information, see [AWS CloudHSM Management Utility (CMU)](cloudhsm_mgmt_util.md).
## Key Management Utility (KMU)
The Key Management Utility (KMU) is a command line tool that helps crypto users (CU) manage keys on the hardware security modules (HSM). For more information, see [AWS CloudHSM Key Management Utility (KMU)](key_mgmt_util.md).
## JCE provider
The AWS CloudHSM JCE provider is compliant with the Java Cryptographic Architecture (JCA). The provider allows you to perform cryptographic operations on the HSM.
The JCE provider is a Linux only component that matches Linux base support. For more information, see [Linux support for AWS CloudHSM Client SDK 3](sdk3-linux.md).
+ For Client SDK 3 requires OpenJDK 1.8
## OpenSSL Dynamic Engine
The AWS CloudHSM OpenSSL Dynamic Engine allows you to offload cryptographic operations to your CloudHSM cluster through the OpenSSL API.
+ For Client SDK 3, the OpenSSL Dynamic Engine is Linux only component that does *not* match Linux base support. See the exclusions below.
+ Requires OpenSSL 1.0.2[f\$1]
**Unsupported platforms: **
+ CentOS 8
+ Red Hat Enterprise Linux (RHEL) 8
+ Ubuntu 18.04 LTS
These platforms ship with a version of OpenSSL incompatible with OpenSSL Dynamic Engine for Client SDK 3. AWS CloudHSM supports these platforms with OpenSSL Dynamic Engine for Client SDK 5.
+ For Client SDK 5, the OpenSSL Dynamic Engine is a Linux only component that requires OpenSSL 1.0.2, 1.1.1, or 3.x.
## Key storage provider (KSP)
Key Storage Provider (KSP) is a cryptographic API specific to the Microsoft Windows operating system.
For Client SDK 3, the CNG and KSP providers is a Windows only component that matches Windows base support. For more information, see [Windows support for AWS CloudHSM Client SDK 3](sdk3-windows.md).
For Client SDK 5, the Key Storage Provider (KSP) is a Windows only component that matches Windows base support. For more information, see [Windows support for AWS CloudHSM Client SDK 5](sdk8-windows.md).
# Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5
In AWS CloudHSM, customer applications perform cryptographic operations using the AWS CloudHSM Client Software Development Kit (SDK). Client SDK 5 is the primary SDK that continues to have new features and platform support added to it.
Client SDK 3 includes two separate command line tools: the CMU for managing users and the KMU for managing keys and performing operations with keys. Client SDK 5 consolidates the functions of the CMU and KMU (tools that were offered with Client SDK 3) into a single tool, the [AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli.md). User management operations can be found under the subcommands [The user category in CloudHSM CLI](cloudhsm_cli-user.md) and [The quorum category in CloudHSM CLI](cloudhsm_cli-qm.md). Key management operations can be found under the [key subcommand](cloudhsm_cli-key.md), and cryptographic operations can be found under the [crypto subcommand](cloudhsm_cli-crypto.md). See [Reference for CloudHSM CLI commands](cloudhsm_cli-reference.md) for a complete list of commands.
For benefits on migrating, see [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md).
See the following topics for detailed instructions on migrating from Client SDK 3 to Client SDK 5. The latest version of AWS CloudHSM Client SDK is 5.16.
+ [Migrate your AWS CloudHSM PKCS \$111 library from Client SDK 3 to Client SDK 5](pkcs11-migrate-to-sdk-5.md)
+ [Migrate your OpenSSL Dynamic Engine from AWS CloudHSM Client SDK 3 to Client SDK 5](openssl-migrate-to-sdk-5.md)
+ [Migrate your Key Storage Provider (KSP) from AWS CloudHSM Client SDK 3 to Client SDK 5](ksp-migrate-to-sdk-5.md)
+ [Migrate your JCE provider from AWS CloudHSM Client SDK 3 to Client SDK 5](java-lib-migrate_to_sdk5.md)
For functionality or use cases that are not supported by CloudHSM CLI, contact [AWS Support](https://support.console.aws.amazon.com/support/home#/).
# Migrate your AWS CloudHSM PKCS \$111 library from Client SDK 3 to Client SDK 5
Use this topic to migrate your AWS CloudHSM [PKCS \$111 library](pkcs11-library.md) from Client SDK 3 to Client SDK 5. For benefits on migrating, see [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md).
In AWS CloudHSM, customer applications perform cryptographic operations using the AWS CloudHSM Client Software Development Kit (SDK). Client SDK 5 is the primary SDK that continues to have new features and platform support added to it.
To review migration instructions for all providers, see [Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5](client-sdk-migration.md).
## Prepare by addressing breaking changes
Review these breaking changes and update your application in your development environment accordingly.
### Wrap mechanisms have changed
****
| Client SDK 3 mechanism | Equivalent Client SDK 5 mechanism |
| --- | --- |
| `CKM_AES_KEY_WRAP` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` |
| `CKM_AES_KEY_WRAP_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` |
| `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD` |
| `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD` |
| `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` | `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD` |
### ECDH
In Client SDK 3, you can use ECDH and specify a KDF. This functionality is not currently available in Client SDK 5. If your application needs this functionality, please reach out to [support](https://support.console.aws.amazon.com/support/home#/).
### Key handles are now session-specific
To successfully use key handles in Client SDK 5, you must obtain key handles each time you run an application. If you have existing applications that will use the same key handles across different sessions, you must modify your code to obtain the key handle each time you run the application. For information on retrieving key handles, see [this AWS CloudHSM PKCS \$111 example](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/find_objects/find_objects.c). This change is in compliance with the [PKCS \$111 2.40 specification](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc416959689).
## Migrate to Client SDK 5
Follow the instructions in this section to migrate from Client SDK 3 to Client SDK 5.
**Note**
Amazon Linux, Ubuntu 16.04, Ubuntu 18.04, CentOS 6, CentOS 8, and RHEL 6 are not currently supported with Client SDK 5. If you are currently using one of these platforms with Client SDK 3, you will need to choose a different platform when migrating to Client SDK 5.
1. Uninstall the PKCS \$111 library for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client-pkcs11
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client-pkcs11
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client-pkcs11
```
------
1. Stop the Client Daemon for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
1. Uninstall the Client Daemon for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
**Note**
Custom configurations need to be enabled again.
1. Install the Client SDK PKCS \$111 library by following the steps in [Install the PKCS \$111 library for AWS CloudHSM Client SDK 5](pkcs11-library-install.md).
1. Client SDK 5 introduces a new configuration file format and command-line bootstrapping tool. To bootstrap your Client SDK 5 PKCS \$111 library, follow the instructions listed in the user guide under [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. In your development environment, test your application. Make updates to your existing code to resolve your breaking changes before your final migration.
## Related topics
+ [Best practices for AWS CloudHSM](best-practices.md)
# Migrate your OpenSSL Dynamic Engine from AWS CloudHSM Client SDK 3 to Client SDK 5
Use this topic to migrate your [OpenSSL Dynamic Engine](openssl-library.md) from AWS CloudHSM Client SDK 3 to Client SDK 5. For benefits on migrating, see [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md).
In AWS CloudHSM, customer applications perform cryptographic operations using the AWS CloudHSM Client Software Development Kit (SDK). Client SDK 5 is the primary SDK that continues to have new features and platform support added to it.
**Note**
Random number generation is not currently supported in Client SDK 5 with OpenSSL Dynamic Engine.
To review migration instructions for all providers, see [Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5](client-sdk-migration.md).
## Migrate to Client SDK 5
Follow the instructions in this section to migrate from Client SDK 3 to Client SDK 5.
**Note**
Amazon Linux, Ubuntu 16.04, Ubuntu 18.04, CentOS 6, CentOS 8, and RHEL 6 are not currently supported with Client SDK 5. If you are currently using one of these platforms with Client SDK 3, you will need to choose a different platform when migrating to Client SDK 5.
1. Uninstall the OpenSSL Dynamic Engine for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client-dyn
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client-dyn
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client-dyn
```
------
1. Stop the Client Daemon for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
1. Uninstall the Client Daemon for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
**Note**
Custom configurations need to be enabled again.
1. Install the Client SDK OpenSSL Dynamic Engine by following the steps in [Install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5](openssl5-install.md).
1. Client SDK 5 introduces a new configuration file format and command-line bootstrapping tool. To bootstrap your Client SDK 5 OpenSSL Dynamic Engine, follow the instructions listed in the user guide under [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. In your development environment, test your application. Make updates to your existing code to resolve your breaking changes before your final migration.
## Related topics
+ [Best practices for AWS CloudHSM](best-practices.md)
# Migrate your Key Storage Provider (KSP) from AWS CloudHSM Client SDK 3 to Client SDK 5
This topic explains how to migrate your [Key Storage Provider (KSP)](ksp-library.md) from AWS CloudHSM Client SDK 3 to Client SDK 5. The latest version of AWS CloudHSM Client SDK is 5.16. For information about migration benefits, see [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md).
In AWS CloudHSM, you use the AWS CloudHSM Client Software Development Kit (SDK) to perform cryptographic operations. Client SDK 5 is the primary SDK that receives new features and platform support updates.
For migration instructions for all providers, see [Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5](client-sdk-migration.md).
## Migrate to Client SDK 5
1. Stop the Client Daemon for Client SDK 3.
```
PS C:\> Stop-Service "AWS CloudHSM Client"
```
1. Install the Client SDK 5 Key Storage Provider (KSP) on your Windows Server instance. For instructions, see [Install the Key storage provider (KSP) for AWS CloudHSM Client SDK 5](ksp-library-install.md).
1. Configure your Client SDK 5 Key Storage Provider (KSP) using the new configuration file format and command-line bootstrapping tool. For instructions, see [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. Key Storage Provider (KSP) for AWS CloudHSM Client SDK 5 includes SDK3 compatibility mode to support key reference files generated in SDK3. For more information, see [SDK3 compatibility mode for Key Storage Provider (KSP) for AWS CloudHSM](ksp-library-configs-sdk3-compatibility-mode.md).
**Note**
You must enable SDK3 compatibility mode when using Client SDK 3 generated key reference files with Client SDK 5.
## Migrate to new Windows Server instances
1. Complete all steps in [Migrate to Client SDK 5](#ksp-migrate-steps) on your new Windows Server instances.
1.
**Check for existing key reference files**
On your original Windows Server instance, check for key reference files in `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`.
+ If key reference files exist, copy all contents under `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP` including `GlobalPartition` to the same directory path on your new Windows Server instance. Create the directory if it doesn't exist.
+ If key reference files don't exist, use `cloudhsm-cli key generate-file --encoding ksp-key-reference` on your new Windows Server instance to create them. For instructions, see [Generating KSP key references (Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference).
1.
**Verify root certificate**
Check your root certificate in the trusted root certification authorities:
```
PS C:\Users\Administrator\Desktop> certutil -store Root
Root "Trusted Root Certification Authorities"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Issuer: CN=MYRootCA
Signature matches Public Key
Root Certificate: Subject matches Issuer
Cert Hash(sha1): cert-hash
No key provider information
Cannot find the certificate and private key for decryption.
CertUtil: -store command completed successfully.
```
**Note**
Note the certificate serial number for use in next step.
1.
**Export root certificate**
Export the root certificate to a file:
```
certutil -store Root certificate-serial-number root-certificate-name.cer
```
1.
**Verify HSM-backend certificate**
Check your HSM-backend certificate in the Personal certificate store:
```
PS C:\Users\Administrator\Desktop> certutil -store My
my "Personal"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US
Non-root Certificate
Cert Hash(sha1): cert-hash
Key Container = key-container-name
Provider = Cavium Key Storage Provider
Private key is NOT exportable
Encryption test passed
CertUtil: -store command completed successfully.
```
**Note**
Note the certificate serial number for use in next step.
1.
**Export HSM-backend certificate**
Export the HSM-backend certificate to a file:
```
certutil -store My certificate-serial-number signed-certificate-name.cer
```
1.
**Import root certificate**
On your new Windows instance:
1. Copy the root CA file to your new Windows instance
1. Import the certificate:
```
certutil -addstore Root root-certificate-name.cer
```
1.
**Verify root certificate installation**
Confirm the root certificate is properly installed:
```
PS C:\Users\Administrator\Desktop> certutil -store Root
Root "Trusted Root Certification Authorities"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Issuer: CN=MYRootCA
Signature matches Public Key
Root Certificate: Subject matches Issuer
Cert Hash(sha1): cert-hash
No key provider information
Cannot find the certificate and private key for decryption.
CertUtil: -store command completed successfully.
```
1.
**Import HSM-backend certificate**
On your new Windows instance:
1. Copy the HSM-backend certificate to your new Windows instance
1. Import the certificate:
```
certutil -addstore My signed-certificate-name.cer
```
1.
**Verify HSM-backend certificate installation**
Confirm the HSM-backend certificate is properly installed:
```
PS C:\Users\Administrator\Desktop> certutil -store My
my "Personal"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US
Non-root Certificate
Cert Hash(sha1): cert-hash
No key provider information
Cannot find the certificate and private key for decryption.
CertUtil: -store command completed successfully.
```
**Note**
Note the certificate serial number for use in subsequent steps.
1.
**Create a key reference file (optional)**
Complete this step only if you need to create new key reference file. Otherwise, proceed to the next step.
**Note**
This feature is only in SDK version 5.16.0 and later.
1. Install [OpenSSL](https://slproweb.com/products/Win32OpenSSL.html) and extract the modulus:
```
openssl x509 -in signed-certificate-name.cer -modulus -noout
```
**Note**
The OpenSSL command outputs the modulus in the format: `Modulus=modulus-value`. Note the *modulus-value* for use in the next command.
1. Create key reference file with CloudHSM CLI, see [Generating KSP key references (Windows)](cloudhsm_cli-key-generate-file.md#key-generate-ksp-key-reference):
```
& "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" key generate-file --encoding ksp-key-reference --filter attr.class=private-key attr.modulus=0xmodulus-value
```
**Note**
The *modulus-value* in CloudHSM CLI command arguments must be prefixed with `0x` to indicate hexadecimal format.
Key reference files are created in `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`.
1.
**Create repair configuration**
Create a file named `repair.txt` with the following content:
```
[Properties]
11 = "" ; Add friendly name property
2 = "{text}" ; Add Key Provider Information property
_continue_="Container=key-container-name&"
_continue_="Provider=Cavium Key Storage Provider&"
_continue_="Flags=0&"
_continue_="KeySpec=2"
```
**Note**
Replace *key-container-name* with the key reference filename from `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`.
1.
**Repair certificate store**
Run the repair command:
```
certutil -repairstore My certificate-serial-number repair.txt
```
**Note**
The certificate serial number is obtained from the previous steps when verifying HSM-backend certificate installation.
1.
**Verify certificate association**
Confirm the certificate is properly associated:
```
PS C:\Users\Administrator\Desktop> certutil -store My
my "Personal"
================ Certificate 0 ================
Serial Number: certificate-serial-number
Issuer: CN=MYRootCA
NotBefore: 2/5/2020 1:38 PM
NotAfter: 2/5/2021 1:48 PM
Subject: CN=www.mydomain.com, OU=Certificate Management, O=Information Technology, L=Houston, S=Texas, C=US
Non-root Certificate
Cert Hash(sha1): cert-hash
Key Container = key-container-name
Provider = Cavium Key Storage Provider
Private key is NOT exportable
ERROR: Could not verify certificate public key against private key
CertUtil: -store command completed successfully.
```
Verify the output shows:
+ The correct key container name
+ The Cavium Key Storage Provider
+ The `ERROR: Could not verify certificate public key against private key` is a known issue, see [Issue: Verification of a certificate store fails](ki-ksp-sdk.md#ki-ksp-1)
1.
**Test your application**
Before completing the migration:
1. Test your application in your development environment
1. Update your code to resolve any breaking changes
1. For application-specific guidance, see [Integrating third-party applications with AWS CloudHSM](third-party-applications.md)
## Verify the migration
After completing the migration steps, verify that:
+ Your certificates are properly installed in the correct certificate stores
+ Key reference files are present in the correct location
+ Your application can perform cryptographic operations using the migrated certificates
## Troubleshooting
If you encounter issues during migration, verify:
+ All certificates are properly exported from the source system
+ Certificate serial numbers match between systems
+ Key container names in the repair.txt file match your key reference files
+ SDK3 compatibility mode is enabled if using SDK3-generated key reference files
## Related topics
+ [Best practices for AWS CloudHSM](best-practices.md)
# Migrate your JCE provider from AWS CloudHSM Client SDK 3 to Client SDK 5
Use this topic to migrate your [JCE provider](java-library.md) from AWS CloudHSM Client SDK 3 to Client SDK 5. For benefits on migrating, see [Benefits of AWS CloudHSM Client SDK 5](client-sdk-5-benefits.md).
In AWS CloudHSM, customer applications perform cryptographic operations using the AWS CloudHSM Client Software Development Kit (SDK). Client SDK 5 is the primary SDK that continues to have new features and platform support added to it.
The Client SDK 3 JCE provider uses custom classes and APIs that are not part of the standard JCE specification. Client SDK 5 for the JCE provider is complaint with the JCE specification and is backwards incompatible with Client SDK 3 in certain areas. Customer applications may require changes as part of the migration to Client SDK 5. This section outlines the changes required for a successful migration.
To review migration instructions for all providers, see [Migrating from AWS CloudHSM Client SDK 3 to Client SDK 5](client-sdk-migration.md).
**Topics**
+ [Prepare by addressing breaking changes](#jce-migration-preparation-sdk5)
+ [Migrate to Client SDK 5](#w2aac25c19c21c15)
+ [Related topics](#java-lib-migrate_to_sdk5-seealso)
## Prepare by addressing breaking changes
Review these breaking changes and update your application in your development environment accordingly.
### The Provider class and name have changed
****
| What has changed | What it was in Client SDK 3 | What it is in Client SDK 5 | Example |
| --- | --- | --- | --- |
| Provider class and name | The JCE provider class in Client SDK 3 is called `CaviumProvider` and has the Provider name `Cavium`. | In Client SDK 5, the Provider class is called `CloudHsmProvider` and has the Provider name `CloudHSM`. | An example of how to initialize the `CloudHsmProvider` object is available in the [AWS CloudHSM GitHub sample repository](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java#L43-L50). |
### Explicit login has changed, implicit has not
****
| What has changed | What it was in Client SDK 3 | What it is in Client SDK 5 | Example |
| --- | --- | --- | --- |
| Explicit login | Client SDK 3 uses the `LoginManager` class for explicit login [1](#explicit_login_sdk3_note). | In Client SDK 5, the `CloudHSM` provider implements `AuthProvider` for explicit login. `AuthProvider` is a standard Java class and follows Java's idiomatic way to log in to a Provider. With improved login state management in Client SDK 5, applications no longer need to monitor and perform login during reconnections[2](#explicit_login_sdk5_note). | For an example on how to use explicit login with Client SDK 5, see the LoginRunner sample in the [AWS CloudHSM GitHub sample repository](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141). |
| Implicit login | No changes are required for implicit login. The same properties file and all environment variables will continue to work for the implicit login when migrating from Client SDK 3 to Client SDK 5. | For an example on how to use implicit login with Client SDK 5, see the [LoginRunner sample](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L143-L202) in the AWS CloudHSM GitHub sample repository. |
+ [1] Client SDK 3 code snippet:
```
LoginManager lm = LoginManager.getInstance();
lm.login(partition, user, pass);
```
+ [2] Client SDK 5 code snippet:
```
// Construct or get the existing provider object
AuthProvider provider = new CloudHsmProvider();
// Call login method on the CloudHsmProvider object
// Here loginHandler is a CallbackHandler
provider.login(null, loginHandler);
```
For an example on how to use explicit login with Client SDK 5, see the [LoginRunner sample](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141) in the AWS CloudHSM GitHub sample repository.
### Key generation has changed
****
| What has changed | What it was in Client SDK 3 | What it is in Client SDK 5 | Example |
| --- | --- | --- | --- |
| Key generation | In Client SDK 3, `Cavium[Key-type]AlgorithmParameterSpec` is used to specify key generation parameters. For a code snippet, see footnote [1](#key_generation_sdk3_note). | In Client SDK 5, `KeyAttributesMap` is used to specify key generation attributes. For a code snippet, see footnote [2](#key_generation_sdk5_note). | For an example on how to use `KeyAttributesMap` to generate a symmetric key, see the [SymmetricKeys sample](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java) in the AWS CloudHSM GitHub sample repository. |
| Key pair generation | In Client SDK 3, `Cavium[Key-type]AlgorithmparameterSpec` is used to specify key pair generation parameters. For a code snippet, see footnote [3](#key_pair_generation_sdk3_note). | In Client SDK 5, `KeyPairAttributesMap` is used to specify these parameters. For a code snippet, see footnote [4](#key_pair_generation_sdk5_note). | For an example on how to use `KeyAttributesMap` to generate an asymmetric key, see the [AsymmetricKeys sample](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java) in the AWS CloudHSM GitHub sample repository. |
+ [1] Client SDK 3 key generation code snippet:
```
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec aesSpec = new CaviumAESKeyGenParameterSpec(
keySizeInBits,
keyLabel,
isExtractable,
isPersistent);
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();
```
+ [2] Client SDK 5 key generation code snippet:
```
KeyGenerator keyGen = KeyGenerator.getInstance("AES",
CloudHsmProvider.PROVIDER_NAME);
final KeyAttributesMap aesSpec = new KeyAttributesMap();
aesSpec.put(KeyAttribute.LABEL, keyLabel);
aesSpec.put(KeyAttribute.SIZE, keySizeInBits);
aesSpec.put(KeyAttribute.EXTRACTABLE, isExtractable);
aesSpec.put(KeyAttribute.TOKEN, isPersistent);
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();
```
+ [3] Client SDK 3 key pair generation code snippet::
```
KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("rsa", "Cavium");
CaviumRSAKeyGenParameterSpec spec = new CaviumRSAKeyGenParameterSpec(
keySizeInBits,
new BigInteger("65537"),
label + ":public",
label + ":private",
isExtractable,
isPersistent);
keyPairGen.initialize(spec);
keyPairGen.generateKeyPair();
```
+ [4] Client SDK 5 key pair generation code snippet:
```
KeyPairGenerator keyPairGen =
KeyPairGenerator.getInstance("RSA", providerName);
// Set attributes for RSA public key
final KeyAttributesMap publicKeyAttrsMap = new KeyAttributesMap();
publicKeyAttrsMap.putAll(additionalPublicKeyAttributes);
publicKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Public");
publicKeyAttrsMap.put(KeyAttribute.MODULUS_BITS, keySizeInBits);
publicKeyAttrsMap.put(KeyAttribute.PUBLIC_EXPONENT,
new BigInteger("65537").toByteArray());
// Set attributes for RSA private key
final KeyAttributesMap privateKeyAttrsMap = new KeyAttributesMap();
privateKeyAttrsMap.putAll(additionalPrivateKeyAttributes);
privateKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Private");
// Create KeyPairAttributesMap and use that to initialize the
// keyPair generator
KeyPairAttributesMap keyPairSpec =
new KeyPairAttributesMapBuilder()
.withPublic(publicKeyAttrsMap)
.withPrivate(privateKeyAttrsMap)
.build();
keyPairGen.initialize(keyPairSpec);
keyPairGen.generateKeyPair();
```
### Finding, deleting, and referencing keys have changed
Finding an already generated key with AWS CloudHSM entails using the KeyStore. Client SDK 3 has two KeyStore types: `Cavium` and `CloudHSM`. Client SDK 5 only has one KeyStore type: `CloudHSM`.
Moving from the `Cavium` KeyStore to `CloudHSM` KeyStore requires a change of KeyStore type. Additionally, Client SDK 3 uses key handles to reference keys, while Client SDK 5 uses key labels. The resulting behavior changes are listed below.
| What has changed | What it was in Client SDK 3 | What it is in Client SDK 5 | Example |
| --- | --- | --- | --- |
| Key references | With Client SDK 3, applications use either key labels or key handles to reference keys in the HSM. They use labels with KeyStore to find a key, or they use handles and create `CaviumKey` objects. | In Client SDK 5, applications can use the [AWS CloudHSM KeyStore Java class for Client SDK 5](alternative-keystore_5.md) to find keys by label. To find keys by handle, use the AWS CloudHSM `KeyStoreWithAttributes` with AWS CloudHSM `KeyReferenceSpec`. | |
| Finding multiple entries | When searching for a key using `getEntry`, `getKey`, or `getCertificate` in scenarios where multiple items with the same criteria exist in the `Cavium` KeyStore, only the first entry found will be returned. | With the AWS CloudHSM `KeyStore` and `KeyStoreWithAttributes`, this same scenario will result in an exception being thrown. To fix this problem, it is recommended to set unique labels for keys using the [Set the attributes of keys with CloudHSM CLI](cloudhsm_cli-key-set-attribute.md) command in CloudHSM CLI. Or use `KeyStoreWithAttributes#getKeys` to return all keys that match the criteria. | |
| Find all keys | It is possible in Client SDK 3 to find all keys in the HSM using `Util.findAllKeys()`. | Client SDK 5 makes finding keys simpler and more efficient by using the `KeyStoreWithAttributes` class. When possible, cache your keys to minimize latency. For more information, see [Effectively manage keys in your application](bp-application-integration.md#bp-manage-application). When you need to retrieve all keys from the HSM, use `KeyStoreWithAttributes#getKeys` with an empty `KeyAttributesMap`. | An example that uses the `KeyStoreWithAttributes` class to find a key is available in the [AWS CloudHSM GitHub sample repository](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L205-L223) and a code snippet is shown in [1](#using_keystore_att_note). |
| Key deletion | Client SDK 3 uses `Util.deleteKey()` to delete a key. | The `Key` object in Client SDK 5 implements the `Destroyable` interface which allows for keys to be deleted using the `destroy()` method of this interface. | An example code showing the delete key functionality can be found on the [CloudHSM GitHub sample repository](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L229-L234). A sample snippet for each SDK is shown in [2](#delete_key_note). |
+ [1] a snippet is shown below:
```
KeyAttributesMap findSpec = new KeyAttributesMap();
findSpec.put(KeyAttribute.LABEL, label);
findSpec.put(KeyAttribute.KEY_TYPE, keyType);
KeyStoreWithAttributes keyStore = KeyStoreWithAttributes.getInstance("CloudHSM");
keyStore.load(null, null);
keyStore.getKey(findSpec);
```
+ [2] Deleting a key in Client SDK 3:
```
Util.deleteKey(key);
```
Deleting a key in Client SDK 5:
```
((Destroyable) key).destroy();
```
### Cipher unwrap operations have changed, other cipher operations have not
**Note**
No changes are required for Cipher encrypt/decrypt/wrap operations.
Unwrap operations require the Client SDK 3 `CaviumUnwrapParameterSpec` class to be replaced with one of the following classes specific to the cryptographic operations listed.
+ `GCMUnwrapKeySpec` for `AES/GCM/NoPadding` unwrap
+ `IvUnwrapKeySpec` for `AESWrap unwrap` and `AES/CBC/NoPadding unwrap`
+ `OAEPUnwrapKeySpec` for `RSA OAEP unwrap`
Example snippet for `OAEPUnwrapkeySpec`:
```
OAEPParameterSpec oaepParameterSpec =
new OAEPParameterSpec(
"SHA-256",
"MGF1",
MGF1ParameterSpec.SHA256,
PSpecified.DEFAULT);
KeyAttributesMap keyAttributesMap =
new KeyAttributesMap(KeyAttributePermissiveProfile.KEY_CREATION);
keyAttributesMap.put(KeyAttribute.TOKEN, true);
keyAttributesMap.put(KeyAttribute.EXTRACTABLE, false);
OAEPUnwrapKeySpec spec = new OAEPUnwrapKeySpec(oaepParameterSpec,
keyAttributesMap);
Cipher hsmCipher =
Cipher.getInstance(
"RSA/ECB/OAEPPadding",
CloudHsmProvider.PROVIDER_NAME);
hsmCipher.init(Cipher.UNWRAP_MODE, key, spec);
```
### Signature operations have not changed
No changes are required for Signature operations.
## Migrate to Client SDK 5
Follow the instructions in this section to migrate from Client SDK 3 to Client SDK 5.
**Note**
Amazon Linux, Ubuntu 16.04, Ubuntu 18.04 CentOS 6, CentOS 8, and RHEL 6 are not currently supported with Client SDK 5. If you are currently using one of these platforms with Client SDK 3, you will need to choose a different platform when migrating to Client SDK 5.
1. Uninstall the JCE provider for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client-jce
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client-jce
```
------
1. Stop the Client Daemon for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
1. Uninstall the Client Daemon for Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
**Note**
Custom configurations need to be enabled again.
1. Install the Client SDK JCE provider by following the steps in [Install the JCE provider for AWS CloudHSM Client SDK 5](java-library-install_5.md).
1. Client SDK 5 introduces a new configuration file format and command-line bootstrapping tool. To bootstrap your Client SDK 5 JCE provider, follow the instructions listed in the user guide under [Bootstrap the Client SDK](cluster-connect.md#connect-how-to).
1. In your development environment, test your application. Make updates to your existing code to resolve your breaking changes before your final migration.
## Related topics
+ [Best practices for AWS CloudHSM](best-practices.md)
# 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
```
------
# Using previous SDK version to work with AWS CloudHSM
****
SDK versions 5.8.0 and earlier have reached their end of support. After March 31, 2025 documentation for SDK versions 3.4.4 and earlier will no longer be available.
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 3. To see what version of Client SDK you're using, see [Check your AWS CloudHSM Client SDK versionTo check the client daemon version](check-client_version.md).
To download, see [Downloads for AWS CloudHSM Client SDK](client-history.md).
**Topics**
+ [Upgrade AWS CloudHSM Client SDK 3 on Linux](client-upgrade.md)
+ [AWS CloudHSM Client SDK 3 supported platforms](sdk3-support.md)
+ [PKCS \$111 library for AWS CloudHSM Client SDK 3](pkcs11-v3-library.md)
+ [OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 3](openssl3-install.md)
+ [JCE provider for AWS CloudHSM Client SDK 3](java-library_3.md)
+ [Cryptography API: Next Generation (CNG) and key storage providers (KSP) for AWS CloudHSM](ksp-v3-library.md)
# Upgrade AWS CloudHSM Client SDK 3 on Linux
****
SDK versions 5.8.0 and earlier have reached their end of support. After March 31, 2025 documentation for SDK versions 3.4.4 and earlier will no longer be available.
With AWS CloudHSM Client SDK 3.1 and higher, the version of the client daemon and any components you install must match to upgrade. For all Linux-based systems, you must use a single command to batch upgrade the client daemon with the same version of the PKCS \$111 library, the Java Cryptographic Extension (JCE) provider, or the OpenSSL Dynamic Engine. This requirement does not apply to Windows-based systems because the binaries for the CNG and KSP providers are already included in the client daemon package.
## To check the client daemon version
+ On a Red Hat-based Linux system (including Amazon Linux and CentOS), use the following command:
```
rpm -qa | grep ^cloudhsm
```
+ On an Debian-based Linux system, use the following command:
```
apt list --installed | grep ^cloudhsm
```
+ On a Windows system, use the following command:
```
wmic product get name,version
```
**Topics**
+ [Prerequisites](#client-upgrade-prerequisites)
+ [Step 1: Stop the client daemon](#client-stop)
+ [Step 2: Upgrade the client SDK](#upgrade-commands)
+ [Step 3: Start the client daemon](#client-start)
## Prerequisites
Download the latest version of AWS CloudHSM client daemon and choose your components.
**Note**
You do not have to install all the components. For every component you have installed, you must upgrade that component to match the version of the client daemon.
### Latest Linux client daemon
------
#### [ Amazon Linux ]
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-latest.el6.x86_64.rpm
```
------
#### [ Amazon Linux 2 ]
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-latest.el7.x86_64.rpm
```
------
#### [ CentOS 7 ]
```
sudo yum install wget
```
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-latest.el7.x86_64.rpm
```
------
#### [ CentOS 8 ]
```
sudo yum install wget
```
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-latest.el8.x86_64.rpm
```
------
#### [ RHEL 7 ]
```
sudo yum install wget
```
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-latest.el7.x86_64.rpm
```
------
#### [ RHEL 8 ]
```
sudo yum install wget
```
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-latest.el8.x86_64.rpm
```
------
#### [ Ubuntu 16.04 LTS ]
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client_latest_amd64.deb
```
------
#### [ Ubuntu 18.04 LTS ]
```
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client_latest_u18.04_amd64.deb
```
------
### Latest PKCS \$111 library
------
#### [ Amazon Linux ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-pkcs11-latest.el6.x86_64.rpm
```
------
#### [ Amazon Linux 2 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
------
#### [ CentOS 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
------
#### [ CentOS 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```
------
#### [ RHEL 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
------
#### [ RHEL 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-pkcs11_latest_amd64.deb
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client-pkcs11_latest_u18.04_amd64.deb
```
------
### Latest OpenSSL Dynamic Engine
------
#### [ Amazon Linux ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-dyn-latest.el6.x86_64.rpm
```
------
#### [ Amazon Linux 2 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
------
#### [ CentOS 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
------
#### [ RHEL 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-dyn_latest_amd64.deb
```
------
### Latest JCE provider
------
#### [ Amazon Linux ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-jce-latest.el6.x86_64.rpm
```
------
#### [ Amazon Linux 2 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
```
------
#### [ CentOS 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
```
------
#### [ CentOS 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-jce-latest.el8.x86_64.rpm
```
------
#### [ RHEL 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
```
------
#### [ RHEL 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-jce-latest.el8.x86_64.rpm
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-jce_latest_amd64.deb
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client-jce_latest_u18.04_amd64.deb
```
------
## Step 1: Stop the client daemon
Use the following command to stop the client daemon.
------
#### [ Amazon Linux ]
```
$ sudo stop cloudhsm-client
```
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo service cloudhsm-client stop
```
------
## Step 2: Upgrade the client SDK
The following command shows the syntax required to upgrade the client daemon and components. Before you run the command, remove any components you don't intend to upgrade.
------
#### [ Amazon Linux ]
```
$ sudo yum install ./cloudhsm-client-latest.el6.x86_64.rpm \
<./cloudhsm-client-pkcs11-latest.el6.x86_64.rpm> \
<./cloudhsm-client-dyn-latest.el6.x86_64.rpm> \
<./cloudhsm-client-jce-latest.el6.x86_64.rpm>
```
------
#### [ Amazon Linux 2 ]
```
$ sudo yum install ./cloudhsm-client-latest.el7.x86_64.rpm \
<./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm> \
<./cloudhsm-client-dyn-latest.el7.x86_64.rpm> \
<./cloudhsm-client-jce-latest.el7.x86_64.rpm>
```
------
#### [ CentOS 7 ]
```
$ sudo yum install ./cloudhsm-client-latest.el7.x86_64.rpm \
<./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm> \
<./cloudhsm-client-dyn-latest.el7.x86_64.rpm> \
<./cloudhsm-client-jce-latest.el7.x86_64.rpm>
```
------
#### [ CentOS 8 ]
```
$ sudo yum install ./cloudhsm-client-latest.el8.x86_64.rpm \
<./cloudhsm-client-pkcs11-latest.el8.x86_64.rpm> \
<./cloudhsm-client-jce-latest.el8.x86_64.rpm>
```
------
#### [ RHEL 7 ]
```
$ sudo yum install ./cloudhsm-client-latest.el7.x86_64.rpm \
<./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm> \
<./cloudhsm-client-dyn-latest.el7.x86_64.rpm> \
<./cloudhsm-client-jce-latest.el7.x86_64.rpm>
```
------
#### [ RHEL 8 ]
```
$ sudo yum install ./cloudhsm-client-latest.el8.x86_64.rpm \
<./cloudhsm-client-pkcs11-latest.el8.x86_64.rpm> \
<./cloudhsm-client-jce-latest.el8.x86_64.rpm>
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt install ./cloudhsm-client_latest_amd64.deb \
\
\
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt install ./cloudhsm-client_latest_u18.04_amd64.deb \
\
```
------
## Step 3: Start the client daemon
Use the following command to start the client daemon.
------
#### [ Amazon Linux ]
```
$ sudo start cloudhsm-client
```
------
#### [ Amazon Linux 2 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 8 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 20.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
# AWS CloudHSM Client SDK 3 supported platforms
****
SDK versions 5.8.0 and earlier have reached their end of support. After March 31, 2025 documentation for SDK versions 3.4.4 and earlier will no longer be available.
AWS CloudHSM Client SDK 3 requires a client daemon and offers command-line tools including, CloudHSM Management Utility (CMU), key management utility (KMU), and the configure tool.
Base support is different for each version of the AWS CloudHSM Client SDK. Typically platform support for components in an SDK 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.
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).
AWS CloudHSM supports only 64-bit operating systems.
**Topics**
+ [Linux support for AWS CloudHSM Client SDK 3](sdk3-linux.md)
+ [Windows support for AWS CloudHSM Client SDK 3](sdk3-windows.md)
+ [HSM compatibility for AWS CloudHSM Client SDK 3](sdk3-hsm-types.md)
# Linux support for AWS CloudHSM Client SDK 3
AWS CloudHSM Client SDK 3 supports the following Linux operating systems and platforms.
+ Amazon Linux
+ Amazon Linux 2
+ CentOS 6.10\$1 2
+ CentOS 7.3\$1
+ CentOS 8 1,4
+ Red Hat Enterprise Linux (RHEL) 6.10\$1 2
+ Red Hat Enterprise Linux (RHEL) 7.3\$1
+ Red Hat Enterprise Linux (RHEL) 8 1
+ Ubuntu 16.04 LTS 3
+ Ubuntu 18.04 LTS 1
[1] No support for OpenSSL Dynamic Engine. For more information, see [OpenSSL Dynamic Engine](sdk3-compare.md#openssl-collapse).
[2] No support for Client SDK 3.3.0 and later.
[3] SDK 3.4 is the last supported release on Ubuntu 16.04.
[4] SDK 3.4 is the last supported release on CentOS 8.3\$1.
# Windows support for AWS CloudHSM Client SDK 3
AWS CloudHSM Client SDK 3 supports the following versions of Windows Server.
+ Microsoft Windows Server 2012
+ Microsoft Windows Server 2012 R2
+ Microsoft Windows Server 2016
+ Microsoft Windows Server 2019
# HSM compatibility for AWS CloudHSM Client SDK 3
The following table describes AWS CloudHSM Client SDK 3 compatibility for HSMs.
| hsm1.medium | hsm2m.medium |
| --- | --- |
| Compatible with Client version SDK 3.1.0 and later. | Not supported. |
# PKCS \$111 library for AWS CloudHSM Client SDK 3
PKCS \$111 is a standard for performing cryptographic operations on hardware security modules (HSM) in AWS CloudHSM.
For information about bootstrapping, see [Connecting to the cluster](cluster-connect.md).
**Topics**
+ [Install the PKCS \$111 library](install-pkcs11-v3.md)
+ [Authenticate to the PKCS \$111 library](pkcs11-v3-pin.md)
+ [Key types](pkcs11-v3-key-types.md)
+ [Mechanisms](pkcs11-v3-mechanisms.md)
+ [API operations](pkcs11-v3-apis.md)
+ [Key attributes](pkcs11-v3-attributes.md)
+ [Code samples](pkcs11-v3-samples.md)
# Install the PKCS \$111 library for AWS CloudHSM Client SDK 3
This topic provides instructions for installing the PKCS \$111 library for the AWS CloudHSM Client SDK 3 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).
## Prerequisites for Client SDK 3
The PKCS \$111 library requires the AWS CloudHSM client.
If you haven't installed and configured the AWS CloudHSM client, do that now by following the steps at [Install the client (Linux)](cmu-install-and-configure-client-linux.md). After you install and configure the client, use the following command to start it.
------
#### [ Amazon Linux ]
```
$ sudo start cloudhsm-client
```
------
#### [ Amazon Linux 2 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 8 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 20.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
## Install the PKCS \$111 library for Client SDK 3
The following command downloads and installs the PKCS \$111 library.
------
#### [ Amazon Linux ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-pkcs11-latest.el6.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el6.x86_64.rpm
```
------
#### [ Amazon Linux 2 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
------
#### [ CentOS 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
------
#### [ CentOS 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```
------
#### [ RHEL 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el7.x86_64.rpm
```
------
#### [ RHEL 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-pkcs11-latest.el8.x86_64.rpm
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-pkcs11_latest_amd64.deb
```
```
$ sudo apt install ./cloudhsm-client-pkcs11_latest_amd64.deb
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client-pkcs11_latest_u18.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-client-pkcs11_latest_u18.04_amd64.deb
```
------
+ If the EC2 instance on which you installed the PKCS \$111 library has no other components from Client SDK 3 installed, you must bootstrap Client SDK 3. You only have to do this once on each instance with a component from Client SDK 3.
+ You can find the PKCS \$111 library files in the following locations:
Linux binaries, configuration scripts, certificates, and log files:
```
/opt/cloudhsm/lib
```
# Authenticate to the PKCS \$111 library for AWS CloudHSM Client SDK 3
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 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 PKCS \$111 library for AWS CloudHSM Client SDK 3
The PKCS \$111 library supports the following key types with AWS CloudHSM Client SDK 3.
****
| Key Type | Description |
| --- | --- |
| RSA | Generate 2048-bit to 4096-bit RSA keys, in increments of 256 bits. |
| EC | Generate keys with the secp224r1 (P-224), secp256r1 (P-256), secp256k1 (Blockchain), secp384r1 (P-384), and secp521r1 (P-521) curves. |
| AES | Generate 128, 192, and 256-bit AES keys. |
| DES3 (Triple DES) | Generate 192-bit DES3 keys. See note [1](#pkcs11-v3-key-note) below for an upcoming change. |
| GENERIC\$1SECRET | Generate 1 to 64 bytes generic secrets. |
+ [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 AWS CloudHSM Client SDK 3
The PKCS \$111 library supports the following algorithms for AWS CloudHSM Client SDK 3:
+ **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,[4](#pkcs11-v3-mech4) AES-GCM, RSA-AES, and RSA-OAEP
+ **Key derivation** – ECDH,[5](#pkcs11-v3-mech5) SP800-108 CTR KDF
## The PKCS \$111 library mechanism-function table
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 table summarizes the combinations of functions and mechanisms supported by AWS CloudHSM.
**Interpreting the supported PKCS \$111 mechanism-function table**
A ✔ mark indicates that AWS CloudHSM supports the mechanism for the function. We do not support all possible functions listed in the PKCS \$111 specification. A ✖ mark indicates that AWS CloudHSM does not yet support the mechanism for the given function, even though the PKCS \$111 standard allows it. Empty cells indicate that PKCS \$111 standard does not support the mechanism for the given function.
**Supported PKCS \$111 library mechanisms and functions**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)
**Mechanism annotations**
+ [1] Single-part operations only.
+ [2] Mechanism is functionally identical to the `CKM_RSA_PKCS_KEY_PAIR_GEN` mechanism, but offers stronger guarantees for `p` and `q` generation.
+ [3.1] AWS CloudHSM approaches hashing differently based on the Client SDK. For Client SDK 3, where we do the hashing depends on data size and whether you’re using single-part or multipart operations.
**Single-part operations in Client SDK 3**
Table 3.1 lists the maximum data set size for each mechanism for Client SDK 3. The entire hash is computed inside the HSM. No support for data sizes greater than 16KB.
**Table 3.1, Maximum data set size for single-part operations**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)
**Multipart operations Client SDK 3**
Support for data sizes greater than 16 KB, but data size determines where the hashing takes place. Data buffers less than 16 KB are hashed inside the HSM. Buffers between 16 KB and the maximum data size for your system are hashed locally in software. *Remember*: Hash functions do not require cryptographic secrets, so you can safely compute them outside of the HSM.
+ [3.2] AWS CloudHSM approaches hashing differently based on the Client SDK. For Client SDK 3, where we do the hashing depends on data size and whether you’re using single-part or multipart operations.
**Single-part operations Client SDK 3**
Table 3.2 lists the maximum data set size for each mechanism for Client SDK 3. No support for data sizes greater than 16KB.
**Table 3.2, Maximum data set size for single-part operations**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)
**Multipart operations Client SDK 3**
Support for data sizes greater than 16 KB, but data size determines where the hashing takes place. Data buffers less than 16 KB are hashed inside the HSM. Buffers between 16 KB and the maximum data size for your system are hashed locally in software. *Remember*: Hash functions do not require cryptographic secrets, so you can safely compute them outside of the HSM.
+ [3.3] 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. The following table lists maximum data size set for each mechanism:
**Table 3.3, Maximum data set size**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-mechanisms.html)
+ [4] 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.
+ [5] **Client SDK 3 only**. Mechanism is implemented to support SSL/TLS offload cases and is executed only partially within the HSM. Before using this mechanism, see "Issue: ECDH key derivation is executed only partially within the HSM" in [Known issues for the PKCS \$111 library for AWS CloudHSMKnown issues for the PKCS \$111 library](ki-pkcs11-sdk.md). `CKM_ECDH1_DERIVE` does not support the secp521r1 (P-521) curve.
+ [6] 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`
+ [7.1] Vendor-defined mechanism. In order to use the CloudHSM vendor defined mechanisms, PKCS\$111 applications must include `/opt/cloudhsm/include/pkcs11/cloudhsm_pkcs11_vendor_defs.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
For additional information regarding AES key wrapping, see [AES Key Wrapping](manage-aes-key-wrapping.md).
+ [8] 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 API operations for AWS CloudHSM Client SDK 3
The PKCS \$111 library supports the following PKCS \$111 API operations for AWS CloudHSM Client SDK 3.
+ `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_SignRecover` (Client SDK 3 support only)
+ `C_SignRecoverInit` (Client SDK 3 support only)
+ `C_SignUpdate`
+ `C_UnWrapKey`
+ `C_Verify`
+ `C_VerifyFinal`
+ `C_VerifyInit`
+ `C_VerifyRecover` (Client SDK 3 support only)
+ `C_VerifyRecoverInit` (Client SDK 3 support only)
+ `C_VerifyUpdate`
+ `C_WrapKey`
# Key attributes in the PKCS \$111 library for AWS CloudHSM Client SDK 3
A 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) sample.
The following topics provide more information about AWS CloudHSM key attributes for Client SDK 3.
**Topics**
+ [Attributes table](pkcs11-v3-attributes-interpreting.md)
+ [Modifying attributes](pkcs11-v3-modify-attr.md)
+ [Interpreting PKCS \$111 library error codes for AWS CloudHSM Client SDK 3](pkcs11-v3-attr-errors.md)
# PKCS \$111 library attributes table for AWS CloudHSM Client SDK 3
The PKCS \$111 library table for AWS CloudHSM Client SDK 3 contains 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-v3-attributes-interpreting.html)
## GenerateKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)
## CreateObject
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)
## UnwrapKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)
## DeriveKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-attributes-interpreting.html)
## GetAttributeValue
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-v3-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.
+ [3] **Client SDK 3 only**. The `CKA_SIGN_RECOVER` attribute is derived from the `CKA_SIGN` attribute. If being set, it can only be set to the same value that is set for `CKA_SIGN`. If not set, it derives the default value of `CKA_SIGN`. Since CloudHSM only supports RSA-based recoverable signature mechanisms, this attribute is currently applicable to RSA public keys only.
+ [4] **Client SDK 3 only**. The `CKA_VERIFY_RECOVER` attribute is derived from the `CKA_VERIFY` attribute. If being set, it can only be set to the same value that is set for `CKA_VERIFY`. If not set, it derives the default value of `CKA_VERIFY`. Since CloudHSM only supports RSA-based recoverable signature mechanisms, this attribute is currently applicable to RSA public keys only.
# Modifying PKCS \$111 library attributes for AWS CloudHSM Client SDK 3
Some attributes of an object can be modified after the object has been created, whereas some cannot. To modify attributes, use the [setAttribute](cloudhsm_mgmt_util-setAttribute.md) command from cloudhsm\$1mgmt\$1util. You can also derive a list of attributes and the constants that represent them by using the [listAttribute](cloudhsm_mgmt_util-listAttributes.md) command from cloudhsm\$1mgmt\$1util.
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 [setAttribute](key_mgmt_util-setAttribute.md) command from key\$1mgmt\$1util 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 3
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/pkcs11-v3-attr-errors.html)
# Code samples for the PKCS \$111 library for AWS CloudHSM Client SDK 3
The code samples on GitHub show you how to accomplish basic tasks using the PKCS \$111 library for AWS CloudHSM.
## Sample code prerequisites
Before running the samples, perform the following steps to set up your environment:
+ Install and configure the [PKCS \$111 library](install-pkcs11-v3.md) for Client SDK 3.
+ 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)
# OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 3
The AWS CloudHSM OpenSSL Dynamic Engine enables you to offload cryptographic operations to your CloudHSM cluster through the OpenSSL API.
AWS CloudHSM Client SDK 3 does require a client daemon to connect to the cluster. It supports:
+ RSA key generation for 2048, 3072, and 4096-bit keys.
+ RSA sign/verify.
+ RSA encrypt/decrypt.
+ Random number generation that is cryptographically secure and FIPS-validated.
Use the following sections to install and configure the AWS CloudHSM dynamic engine for OpenSSL.
**Topics**
+ [Prerequisites for OpenSSL Dynamic Engine with AWS CloudHSM Client SDK 3](openssl3-install-dyn3-prereqs.md)
+ [Install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 3](openssl3-install-openssl-library.md)
+ [Use the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 3](openssl3-use-library.md)
# Prerequisites for OpenSSL Dynamic Engine with AWS CloudHSM Client SDK 3
For information about platform support, see [AWS CloudHSM Client SDK 3 supported platforms](sdk3-support.md).
Before you can use the AWS CloudHSM dynamic engine for OpenSSL with Client SDK 3, you need the AWS CloudHSM client.
The client is a daemon that establishes end-to-end encrypted communication with the HSMs in your cluster, and the OpenSSL engine communicates locally with the client. To install and configure the AWS CloudHSM client, see [Install the client (Linux)](cmu-install-and-configure-client-linux.md). Then use the following command to start it.
------
#### [ Amazon Linux ]
```
$ sudo start cloudhsm-client
```
------
#### [ Amazon Linux 2 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 6 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 6 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
# Install the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 3
The following steps describe how to install and configure the AWS CloudHSM dynamic engine for OpenSSL with Client SDK 3. For information about upgrading, see [Upgrade Client SDK 3](client-upgrade.md).
**To install and configure the OpenSSL engine**
1. Use the following commands to download and install the OpenSSL engine.
------
#### [ Amazon Linux ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-dyn-latest.el6.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-dyn-latest.el6.x86_64.rpm
```
------
#### [ Amazon Linux 2 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
------
#### [ CentOS 6 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-dyn-latest.el6.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-dyn-latest.el6.x86_64.rpm
```
------
#### [ CentOS 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
------
#### [ RHEL 6 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-dyn-latest.el6.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-dyn-latest.el6.x86_64.rpm
```
------
#### [ RHEL 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-dyn-latest.el7.x86_64.rpm
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-dyn_latest_amd64.deb
```
```
$ sudo apt install ./cloudhsm-client-dyn_latest_amd64.deb
```
------
The OpenSSL engine is installed at `/opt/cloudhsm/lib/libcloudhsm_openssl.so`.
1. Use the following command to set an environment variable named `n3fips_password` that contains the credentials of a crypto user (CU).
```
$ export n3fips_password=:
```
# Use the OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 3
To use the AWS CloudHSM dynamic engine for OpenSSL from an OpenSSL-integrated application, ensure that your application uses the OpenSSL dynamic engine named `cloudhsm`. The shared library for the dynamic engine is located at `/opt/cloudhsm/lib/libcloudhsm_openssl.so`.
To use the AWS CloudHSM dynamic engine for OpenSSL from the OpenSSL command line, use the `-engine` option to specify the OpenSSL dynamic engine named `cloudhsm`. For example:
```
$ openssl s_server -cert -key -engine cloudhsm
```
# JCE provider for AWS CloudHSM Client SDK 3
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.
**Topics**
+ [Install the JCE provider for AWS CloudHSM Client SDK 3](java-library-install.md)
+ [Key management basics in the JCE provider for AWS CloudHSM Client SDK 3](java-library-key-basics.md)
+ [Supported mechanisms for Client SDK 3 for AWS CloudHSM Client SDK 3](java-lib-supported.md)
+ [Supported Java key attributes for AWS CloudHSM Client SDK 3](java-lib-attributes.md)
+ [Code samples for the AWS CloudHSM software library for Java for Client SDK 3](java-samples_3.md)
+ [AWS CloudHSM KeyStore Java class for Client SDK 3](alternative-keystore.md)
# Install the JCE provider for AWS CloudHSM Client SDK 3
Before you can use the JCE provider, you need the AWS CloudHSM client.
The client is a daemon that establishes end-to-end encrypted communication with the HSMs in your cluster. The JCE provider communicates locally with the client. If you haven't installed and configured the AWS CloudHSM client package, do that now by following the steps at [Install the client (Linux)](cmu-install-and-configure-client-linux.md). After you install and configure the client, use the following command to start it.
Note that the JCE provider is supported only on Linux and compatible operating systems.
------
#### [ Amazon Linux ]
```
$ sudo start cloudhsm-client
```
------
#### [ Amazon Linux 2 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ CentOS 8 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
#### [ Ubuntu 20.04 LTS ]
```
$ sudo systemctl start cloudhsm-client
```
------
Use the following sections to install, validate, and provide credentials to the provider.
**Topics**
+ [Step 1: Install the JCE provider](#install-java-library)
+ [Step 2: Validate the installation](#validate-install)
+ [Step 3: Provide credentials to the JCE provider](#java-library-credentials)
## Step 1: Install the JCE provider
Use the following commands to download and install the JCE provider. This provider is supported only on Linux and compatible operating systems.
**Note**
For upgrading, see [Upgrade Client SDK 3](client-upgrade.md).
------
#### [ Amazon Linux ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-jce-latest.el6.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-jce-latest.el6.x86_64.rpm
```
------
#### [ Amazon Linux 2 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-jce-latest.el7.x86_64.rpm
```
------
#### [ CentOS 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-jce-latest.el7.x86_64.rpm
```
------
#### [ CentOS 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-jce-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-jce-latest.el8.x86_64.rpm
```
------
#### [ RHEL 7 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-jce-latest.el7.x86_64.rpm
```
------
#### [ RHEL 8 ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-jce-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-client-jce-latest.el8.x86_64.rpm
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-jce_latest_amd64.deb
```
```
$ sudo apt install ./cloudhsm-client-jce_latest_amd64.deb
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client-jce_latest_u18.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-client-jce_latest_u18.04_amd64.deb
```
------
After you run the preceding commands, you can find the following JCE provider files:
+ `/opt/cloudhsm/java/cloudhsm-.jar`
+ `/opt/cloudhsm/java/cloudhsm-test-.jar`
+ `/opt/cloudhsm/java/hamcrest-all-1.3.jar`
+ `/opt/cloudhsm/java/junit.jar`
+ `/opt/cloudhsm/java/log4j-api-2.17.1.jar`
+ `/opt/cloudhsm/java/log4j-core-2.17.1.jar`
+ `/opt/cloudhsm/lib/libcaviumjca.so`
## Step 2: Validate the installation
Perform basic operations on the HSM to validate the installation.
**To validate JCE provider installation**
1. (Optional) If you don't already have Java installed in your environment, use the following command to install it.
------
#### [ Linux (and compatible libraries) ]
```
$ sudo yum install java-1.8.0-openjdk
```
------
#### [ Ubuntu ]
```
$ sudo apt-get install openjdk-8-jre
```
------
1. Use the following commands to set the necessary environment variables. Replace ** and ** with the credentials of a crypto user (CU).
```
$ export LD_LIBRARY_PATH=/opt/cloudhsm/lib
```
```
$ export HSM_PARTITION=PARTITION_1
```
```
$ export HSM_USER=
```
```
$ export HSM_PASSWORD=
```
1. Use the following command to run the basic functionality test. If successful, the command's output should be similar to the one that follows.
```
$ java8 -classpath "/opt/cloudhsm/java/*" org.junit.runner.JUnitCore TestBasicFunctionality
JUnit version 4.11
.2018-08-20 17:53:48,514 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:33) - Adding provider.
2018-08-20 17:53:48,612 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:42) - Logging in.
2018-08-20 17:53:48,612 INFO [main] cfm2.LoginManager (LoginManager.java:104) - Looking for credentials in HsmCredentials.properties
2018-08-20 17:53:48,612 INFO [main] cfm2.LoginManager (LoginManager.java:122) - Looking for credentials in System.properties
2018-08-20 17:53:48,613 INFO [main] cfm2.LoginManager (LoginManager.java:130) - Looking for credentials in System.env
SDK Version: 2.03
2018-08-20 17:53:48,655 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:54) - Generating AES Key with key size 256.
2018-08-20 17:53:48,698 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:63) - Encrypting with AES Key.
2018-08-20 17:53:48,705 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:84) - Deleting AES Key.
2018-08-20 17:53:48,707 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:92) - Logging out.
Time: 0.205
OK (1 test)
```
## Step 3: Provide credentials to the JCE provider
HSMs need to authenticate your Java application before the application can use them. Each application can use one session. HSMs authenticate a session by using either explicit login or implicit login method.
**Explicit login** – This method lets you provide CloudHSM credentials directly in the application. It uses the `LoginManager.login()` method, where you pass the CU user name, password, and the HSM partition ID. For more information about using the explicit login method, see the [Login to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java) code example.
**Implicit login** – This method lets you set CloudHSM credentials either in a new property file, system properties, or as environment variables.
+ **New property file** – Create a new file named `HsmCredentials.properties` and add it to your application's `CLASSPATH`. The file should contain the following:
```
HSM_PARTITION = PARTITION_1
HSM_USER =
HSM_PASSWORD =
```
+ **System properties** – Set credentials through system properties when running your application. The following examples show two different ways that you can do this:
```
$ java -DHSM_PARTITION=PARTITION_1 -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_PARTITION","PARTITION_1");
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
+ **Environment variables** – Set credentials as environment variables.
```
$ export HSM_PARTITION=PARTITION_1
$ export HSM_USER=
$ export 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. `HsmCredentials.properties`
1. System properties
1. Environment variables
**Error handling**
The error handling is easier with the explicit login than the implicit login method. When you use the `LoginManager` class, you have more control over how your application deals with failures. The implicit login method makes error handling difficult to understand when the credentials are invalid or the HSMs are having problems in authenticating session.
# Key management basics in the JCE provider for AWS CloudHSM Client SDK 3
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/master/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_3.md).
# Supported mechanisms for Client SDK 3 for AWS CloudHSM Client SDK 3
This topic provides information about supported mechanisms for JCE provider with AWS CloudHSM Client SDK 3. For information about the Java Cryptography Architecture (JCA) interfaces and engine classes supported by AWS CloudHSM, see the following topics.
**Topics**
+ [Supported keys](#java-keys)
+ [Supported ciphers](#java-ciphers)
+ [Supported digests](#java-digests)
+ [Supported hash-based message authentication code (HMAC) algorithms](#java-mac)
+ [Supported sign/verify mechanisms](#java-sign-verify)
+ [Mechanism annotations](#w2aac25c23c25c11c17)
## Supported keys
The AWS CloudHSM software library for Java enables you to generate the following key types.
+ AES – 128, 192, and 256-bit AES keys.
+ DESede – 92 bit 3DES key. See note [1](#java-keys-note-1) below for an upcoming change.
+ ECC key pairs for NIST curves secp256r1 (P-256), secp384r1 (P-384), and secp256k1 (Blockchain).
+ RSA – 2048-bit to 4096-bit RSA keys, in increments of 256 bits.
In addition to standard parameters, we support the following parameters for each key that is generated.
+ **Label**: A key label that you can use to search for keys.
+ **isExtractable**: Indicates whether the key can be exported from the HSM.
+ **isPersistent**: Indicates whether the key remains on the HSM when the current session ends.
**Note**
Java library version 3.1 provides the ability to specify parameters in greater detail. For more information, see [Supported Java Attributes](java-lib-attributes.md).
## Supported ciphers
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`. |
| AES | ECB | `AES/ECB/NoPadding` `AES/ECB/PKCS5Padding` | Implements Cipher.ENCRYPT\$1MODE and Cipher.DECRYPT\$1MODE. Use Transformation AES. |
| AES | CTR | `AES/CTR/NoPadding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. |
| AES | GCM | AES/GCM/NoPadding | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`, `Cipher.WRAP_MODE`, and `Cipher.UNWRAP_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/ZeroPadding` `AESWrap/ECB/NoPadding` `AESWrap/ECB/PKCS5Padding` | Implements `Cipher.WRAP_MODE`, and `Cipher.UNWRAP_MODE`. Use Transformation AES. |
| DESede (Triple DES) | CBC | `DESede/CBC/NoPadding` `DESede/CBC/PKCS5Padding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. The key generation routines accept a size of 168 or 192 bits. However, internally, all DESede keys are 192 bits. See note [1](#java-keys-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`. The key generation routines accept a size of 168 or 192 bits. However, internally, all DESede keys are 192 bits. See note [1](#java-keys-note-1) below for an upcoming change. |
| RSA | ECB | `RSA/ECB/NoPadding``RSA/ECB/PKCS1Padding` | Implements `Cipher.ENCRYPT_MODE` and `Cipher.DECRYPT_MODE`. See note [1](#java-keys-note-1) below for an upcoming change. |
| RSA | ECB | `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.ENCRYPT_MODE`, `Cipher.DECRYPT_MODE`, `Cipher.WRAP_MODE`, and `Cipher.UNWRAP_MODE`. `OAEPPadding` is `OAEP` with the `SHA-1` padding type. |
| RSAAESWrap | ECB | OAEPPADDING | Implements Cipher.WRAP\$1Mode and Cipher.UNWRAP\$1MODE. |
## Supported digests
The AWS CloudHSM software library for Java supports the following message digests.
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
**Note**
Data under 16 KB in length are hashed on the HSM, while larger data are hashed locally in software.
## Supported hash-based message authentication code (HMAC) algorithms
The AWS CloudHSM software library for Java supports the following HMAC algorithms.
+ `HmacSHA1`
+ `HmacSHA224`
+ `HmacSHA256`
+ `HmacSHA384`
+ `HmacSHA512`
## Supported sign/verify mechanisms
The AWS CloudHSM software library for Java supports the following types of signature and verification.
**RSA Signature Types**
+ `NONEwithRSA`
+ `SHA1withRSA`
+ `SHA224withRSA`
+ `SHA256withRSA`
+ `SHA384withRSA`
+ `SHA512withRSA`
+ `SHA1withRSA/PSS`
+ `SHA224withRSA/PSS`
+ `SHA256withRSA/PSS`
+ `SHA384withRSA/PSS`
+ `SHA512withRSA/PSS`
**ECDSA Signature Types**
+ `NONEwithECDSA`
+ `SHA1withECDSA`
+ `SHA224withECDSA`
+ `SHA256withECDSA`
+ `SHA384withECDSA`
+ `SHA512withECDSA`
## 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.
# Supported Java key attributes for AWS CloudHSM Client SDK 3
This topic describes how to use a proprietary extension for the Java library version 3.1 to set key attributes for AWS CloudHSM Client SDK 3. Use this extension to set supported key attributes and their values during these operations:
+ Key generation
+ Key import
+ Key unwrap
**Note**
The extension for setting custom key attributes is an optional feature. If you already have code that functions in Java library version 3.0, you do not need to modify that code. Keys you create will continue to contain the same attributes as before.
**Topics**
+ [Understanding attributes](#java-understanding-attributes)
+ [Supported attributes](#java-attributes)
+ [Setting attributes for a key](#java-setting-attributes)
+ [Putting it all together](#java-attributes-summary)
## Understanding attributes
You use key attributes to specify what actions are permitted on key objects, including public, private or secret keys. You define key attributes and values during key object creation operations.
However, 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 Java library version 3.1, 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 table below. As a best practice, only set values for attributes you wish to make restrictive. If you don’t specify a value, 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 | |
| CKA\$1TOKEN | FALSE | FALSE | FALSE | A permanent key which is replicated across all HSMs in the cluster and included in backups. CKA\$1TOKEN = FALSE implies a session key, which is only loaded onto one HSM and automatically erased when the connection to the HSM is broken. |
| CKA\$1LABEL | | | | A user-defined string. It allows you to conveniently identify keys on your HSM. |
| CKA\$1EXTRACTABLE | TRUE | | TRUE | True indicates you can export this key out of the HSM. |
| CKA\$1ENCRYPT | TRUE | TRUE | | True indicates you can use the key to encrypt any buffer. |
| CKA\$1DECRYPT | TRUE | | TRUE | True indicates you can use the key to decrypt any buffer. You generally set this to FALSE for a key whose CKA\$1WRAP is set to true. |
| CKA\$1WRAP | TRUE | TRUE | | True indicates you can use the key to wrap another key. You will generally set this to FALSE for private keys. |
| CKA\$1UNWRAP | TRUE | | TRUE | True indicates you can use the key to unwrap (import) another key. |
| CKA\$1SIGN | 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. |
| CKA\$1VERIFY | TRUE | TRUE | | True indicates you can use the key to verify a signature. This is generally set to FALSE for private keys. |
| CKA\$1PRIVATE | 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 CloudHSM until they are authenticated, even if this attribute is set to FALSE. |
**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
`CloudHsmKeyAttributesMap` is a [Java Map](https://devdocs.io/openjdk~8/java/util/map)-like object, which you can use to set attribute values for key objects. The methods for `CloudHsmKeyAttributesMap` 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 | `CloudHSMKeyAttributesMap` 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).
### Builder pattern example
Developers will generally find it more convenient to utilize classes through the Builder pattern. As examples:
```
import com.amazonaws.cloudhsm.CloudHsmKeyAttributes;
import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap;
import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap;
CloudHsmKeyAttributesMap keyAttributesSessionDecryptionKey =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "ExtractableSessionKeyEncryptDecrypt")
.put(CloudHsmKeyAttributes.CKA_WRAP, false)
.put(CloudHsmKeyAttributes.CKA_UNWRAP, false)
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_VERIFY, false)
.build();
CloudHsmKeyAttributesMap keyAttributesTokenWrappingKey =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "TokenWrappingKey")
.put(CloudHsmKeyAttributes.CKA_TOKEN, true)
.put(CloudHsmKeyAttributes.CKA_ENCRYPT, false)
.put(CloudHsmKeyAttributes.CKA_DECRYPT, false)
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_VERIFY, false)
.build();
```
Developers may also utilize pre-defined attribute sets as a convenient way to enforce best practices in key templates. As an example:
```
//best practice template for wrapping keys
CloudHsmKeyAttributesMap commonKeyAttrs = new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, false)
.put(CloudHsmKeyAttributes.CKA_DECRYPT, false)
.build();
// initialize a new instance of CloudHsmKeyAttributesMap by copying commonKeyAttrs
// but with an appropriate label
CloudHsmKeyAttributesMap firstKeyAttrs = new CloudHsmKeyAttributesMap(commonKeyAttrs);
firstKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, "key label");
// alternatively, putAll() will overwrite existing values to enforce conformance
CloudHsmKeyAttributesMap secondKeyAttrs = new CloudHsmKeyAttributesMap();
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_DECRYPT, true);
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_ENCRYPT, true);
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, “safe wrapping key”);
secondKeyAttrs.putAll(commonKeyAttrs); // will overwrite CKA_DECRYPT to be FALSE
```
### Setting attributes for a key pair
Use the Java class `CloudHsmKeyPairAttributesMap` to handle key attributes for a key pair. `CloudHsmKeyPairAttributesMap` encapsulates two `CloudHsmKeyAttributesMap` 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 `CloudHsmKeyAttributes` 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.
### Builder pattern example
Developers will generally find it more convenient to set key attributes through the Builder pattern. For example:
```
import com.amazonaws.cloudhsm.CloudHsmKeyAttributes;
import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap;
import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap;
//specify attributes up-front
CloudHsmKeyAttributesMap keyAttributes =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_LABEL, "PublicCertSerial12345")
.build();
CloudHsmKeyPairAttributesMap keyPairAttributes =
new CloudHsmKeyPairAttributesMap.Builder()
.withPublic(keyAttributes)
.withPrivate(
new CloudHsmKeyAttributesMap.Builder() //or specify them inline
.put(CloudHsmKeyAttributes.CKA_LABEL, "PrivateCertSerial12345")
.put (CloudHSMKeyAttributes.CKA_WRAP, FALSE)
.build()
)
.build();
```
**Note**
For more information about this proprietary extension, see the [Javadoc](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Docs/CloudHsm_CustomKeyAttributes_Javadoc.zip) archive and the [sample](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CustomKeyAttributesRunner.java) on GitHub. To explore the Javadoc, download and expand the archive.
## Putting it all together
To specify key attributes with your key operations, follow these steps:
1. Instantiate `CloudHsmKeyAttributesMap` for symmetric keys or `CloudHsmKeyPairAttributesMap` for key pairs.
1. Define the attributes object from step 1 with the required key attributes and values.
1. Instantiate a `Cavium*ParameterSpec` class, corresponding to your specific key type, and pass into its constructor this configured attributes object.
1. Pass this `Cavium*ParameterSpec` object into a corresponding crypto class or method.
For reference, the following table contains the `Cavium*ParameterSpec` classes and methods which support custom key attributes.
****
| Key Type | Parameter Spec Class | Example Constructors |
| --- | --- | --- |
| Base Class | CaviumKeyGenAlgorithmParameterSpec | CaviumKeyGenAlgorithmParameterSpec(CloudHsmKeyAttributesMap keyAttributesMap) |
| DES | CaviumDESKeyGenParameterSpec | CaviumDESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) |
| RSA | CaviumRSAKeyGenParameterSpec | CaviumRSAKeyGenParameterSpec(int keysize, BigInteger publicExponent, CloudHsmKeyPairAttributesMap keyPairAttributesMap) |
| Secret | CaviumGenericSecretKeyGenParameterSpec | CaviumGenericSecretKeyGenParameterSpec(int size, CloudHsmKeyAttributesMap keyAttributesMap) |
| AES | CaviumAESKeyGenParameterSpec | CaviumAESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) |
| EC | CaviumECGenParameterSpec | CaviumECGenParameterSpec(String stdName, CloudHsmKeyPairAttributesMap keyPairAttributesMap) |
### Sample code: Generate and wrap a key
These brief code samples demonstrate the steps for two different operations: Key Generation and Key Wrapping:
```
// Set up the desired key attributes
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec keyAttributes = new CaviumAESKeyGenParameterSpec(
256,
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "MyPersistentAESKey")
.put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, true)
.put(CloudHsmKeyAttributes.CKA_TOKEN, true)
.build()
);
// Assume we already have a handle to the myWrappingKey
// Assume we already have the wrappedBytes to unwrap
// Unwrap a key using Custom Key Attributes
CaviumUnwrapParameterSpec unwrapSpec = new CaviumUnwrapParameterSpec(myInitializationVector, keyAttributes);
Cipher unwrapCipher = Cipher.getInstance("AESWrap", "Cavium");
unwrapCipher.init(Cipher.UNWRAP_MODE, myWrappingKey, unwrapSpec);
Key unwrappedKey = unwrapCipher.unwrap(wrappedBytes, "AES", Cipher.SECRET_KEY);
```
# Code samples for the AWS CloudHSM software library for Java for Client SDK 3
This topic provides resources and information on Java code samples for AWS CloudHSM Client SDK 3.
## Prerequisites
Before running the samples, you must set up your environment:
+ Install and configure the [Java Cryptographic Extension (JCE) provider](java-library-install.md#install-java-library) and the [AWS CloudHSM client package](cmu-install-and-configure-client-linux.md).
+ 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.md#java-library-credentials).
## 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/).
+ [Log in to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)
+ [Manage keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [Generate an AES key](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)
+ [Encrypt and decrypt with AES-GCM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/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/master/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java)
+ [Encrypt and decrypt with D3DES-ECB]( https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java)**see note [1](#java-samples-code-note-1)**
+ [Wrap and unwrap keys with AES-GCM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMWrappingRunner.java)
+ [Wrap and unwrap keys with AES](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/AESWrappingRunner.java)
+ [Wrap and unwrap keys with RSA](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/RSAWrappingRunner.java)
+ [Use supported key attributes](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CustomKeyAttributesRunner.java)
+ [Enumerate keys in the key store](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.java)
+ [ Use the CloudHSM key store](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CloudHSMKeyStoreExampleRunner.java)
+ [Sign messages in a multi-threaded sample](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/SignThreadedRunner.java)
+ [Sign and Verify with EC Keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.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 KeyStore Java class for Client SDK 3
The AWS CloudHSM `KeyStore` class provides a special-purpose PKCS12 key store that allows access to AWS CloudHSM keys through applications such as **keytool** and **jarsigner**. This key store can store certificates along with your key data and correlate them to key data stored on AWS CloudHSM.
**Note**
Because certificates are public information, and to maximize storage capacity for cryptographic keys, AWS CloudHSM does not support storing certificates on HSMs.
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://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html).
## Choose the appropriate key store for AWS CloudHSM Client SDK 3
The AWS CloudHSM Java Cryptographic Extension (JCE) provider comes with a default pass-through, read-only key store that passes all transactions to the HSM. This default key store is distinct from the special-purpose AWS CloudHSM KeyStore. In most situations, you will obtain better runtime performance and throughput by using the default. You should only use the AWS CloudHSM KeyStore for applications where you require support for certificates and certificate-based operations in addition to offloading key operations to the HSM.
Although both key stores use the JCE provider for operations, they are independent entities and do not exchange information with each other.
Load the default key store for your Java application as follows:
```
KeyStore ks = KeyStore.getInstance("Cavium");
```
Load the special-purpose CloudHSM KeyStore as follows:
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## Initialize the AWS CloudHSM KeyStore for Client SDK 3
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/master/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 the AWS CloudHSM KeyStore for AWS CloudHSM Client SDK 3
A CloudHSM KeyStore object is generally used through a third-party application such as [jarsigner](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/jarsigner.html) or [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html). You can also access the object directly with code.
AWS CloudHSM KeyStore complies with the JCE [Class KeyStore](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html) 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 with CloudHSM’s [key\$1mgmt\$1util](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util.html) tool.
+ `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 3.**
+ `SetKeyEntry` with `Key` object
Assigns the given key to the given alias and stores it inside the HSM. If the `Key` object is not of type `CaviumKey`, the key is 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).
# Cryptography API: Next Generation (CNG) and key storage providers (KSP) for AWS CloudHSM
The AWS CloudHSM client for Windows includes CNG and KSP providers.
*Key storage providers* (KSPs) enable key storage and retrieval. For example, if you add the Microsoft Active Directory Certificate Services (AD CS) role to your Windows server and choose to create a new private key for your certificate authority (CA), you can choose the KSP that will manage key storage. When you configure the AD CS role, you can choose this KSP. For more information, see [Create Windows Server CA](win-ca-overview-sdk5.md#win-ca-setup-sdk5).
*Cryptography API: Next Generation (CNG)* is a cryptographic API specific to the Microsoft Windows operating system. CNG enables developers to use cryptographic techniques to secure Windows-based applications. At a high level, the AWS CloudHSM implementation of CNG provides the following functionality:
+ **Cryptographic Primitives** – enable you to perform fundamental cryptographic operations.
+ **Key Import and Export** – enables you to import and export asymmetric keys.
+ **Data Protection API (CNG DPAPI)** – enables you to easily encrypt and decrypt data.
+ **Key Storage and Retrieval** -–enables you to securely store and isolate the private key of an asymmetric key pair.
**Topics**
+ [Verify the KSP and CNG Providers for AWS CloudHSM](ksp-v3-library-install.md)
+ [Prerequisites for using the AWS CloudHSM Windows Client](ksp-library-prereq.md)
+ [Associate an AWS CloudHSM key with a certificate](ksp-library-associate-key-certificate.md)
+ [Code sample for CNG provider for AWS CloudHSM](ksp-library-sample.md)
# Verify the KSP and CNG Providers for AWS CloudHSM
The KSP and CNG providers are installed when you install the Windows AWS CloudHSM client. You can install the client by following the steps at [Install the client (Windows)](kmu-install-and-configure-client-win.md).
Use the following sections to verify the installation of the providers.
## Configure and run the Windows AWS CloudHSM client
To start the Windows CloudHSM client, you must first satisfy the [Prerequisites](ksp-library-prereq.md). Then, update the configuration files that the providers use and start the client by completing the steps below. You need to do these steps the first time you use the KSP and CNG providers and after you add or remove HSMs in your cluster. This way, AWS CloudHSM is able to synchronize data and maintain consistency across all HSMs in the cluster.
### Step 1: Stop the AWS CloudHSM client
Before you update the configuration files that the providers use, stop the AWS CloudHSM client. If the client is already stopped, running the stop command has no effect.
+ For Windows client 1.1.2\$1:
```
C:\Program Files\Amazon\CloudHSM>net.exe stop AWSCloudHSMClient
```
+ For Windows clients 1.1.1 and older:
Use **Ctrl**\$1**C** in the command window where you started the AWS CloudHSM client.
### Step 2: Update the AWS CloudHSM configuration files
This step uses the `-a` parameter of the [Configure tool](configure-tool.md) to add the elastic network interface (ENI) IP address of one of the HSMs in the cluster to the configuration file.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" -a
```
To get the ENI IP address of an HSM in your cluster, navigate to the AWS CloudHSM console, choose **clusters**, and select the desired cluster. You can also use the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation, the [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) command, or the [Get-HSM2Cluster](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-HSM2Cluster.html) PowerShell cmdlet. Type only one ENI IP address. It does not matter which ENI IP address you use.
### Step 3: Start the AWS CloudHSM client
Next, start or restart the AWS CloudHSM client. When the AWS CloudHSM client starts, it uses the ENI IP address in its configuration file to query the cluster. Then it adds the ENI IP addresses of all HSMs in the cluster to the cluster information file.
+ For Windows client 1.1.2\$1:
```
C:\Program Files\Amazon\CloudHSM>net.exe start AWSCloudHSMClient
```
+ For Windows clients 1.1.1 and older:
```
C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg
```
## Checking the KSP and CNG providers
You can use either of the following commands to determine which providers are installed on your system. The commands list the registered KSP and CNG providers. The AWS CloudHSM client does not need to be running.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\ksp_config.exe" -enum
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\cng_config.exe" -enum
```
To verify that the KSP and CNG providers are installed on your Windows Server EC2 instance, you should see the following entries in the list:
```
Cavium CNG Provider
Cavium Key Storage Provider
```
If the CNG provider is missing, run the following command.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\cng_config.exe" -register
```
If the KSP provider is missing, run the following command.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\ksp_config.exe" -register
```
# Prerequisites for using the AWS CloudHSM Windows Client
Before you can start the Windows AWS CloudHSM client and use the KSP and CNG providers, you must set the login credentials for the HSM on your system. You can set credentials through either Windows Credentials Manager or system environment variable. We recommend you use Windows Credential Manager for storing credentials. This option is available with AWS CloudHSM client version 2.0.4 and later. Using environment variable is easier to set up, but less secure than using Windows Credential Manager.
## Windows Credential Manager
You can use either the `set_cloudhsm_credentials` utility or the Windows Credentials Manager interface.
+ **Using the `set_cloudhsm_credentials` utility**:
The `set_cloudhsm_credentials` utility is included in your Windows installer. 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 that is included in the installer.
1. Go to the `C:\Program Files\Amazon\CloudHSM\tools\` folder.
1. Run the `set_cloudhsm_credentials.exe` file with the CU username and password parameters.
```
set_cloudhsm_credentials.exe --username --password
```
+ **Using the Credential Manager interface**:
You can use the Credential Manager interface to manually manage your credentials.
1. To open Credential Manager, type `credential manager` in the search box on the taskbar and select **Credential Manager**.
1. Select **Windows Credentials** to manage Windows credentials.
1. Select **Add a generic credential** and fill out the details as follows:
+ In **Internet or Network Address**, enter the target name as `cloudhsm_client`.
+ In **Username** and **Password** enter the CU credentials.
+ Click **OK**.
## System environment variables
You can set system environment variables that identify an HSM and a [crypto user](understanding-users-cmu.md#crypto-user-cmu) (CU) for your Windows application. You can use the [**setx** command](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) to set system environment variables, or set permanent system environment variables [programmatically](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx) or in the **Advanced** tab of the Windows **System Properties** Control Panel.
**Warning**
When you set credentials through system environment variables, the password is available in plaintext on a user’s system. To overcome this problem, use Windows Credential Manager.
Set the following system environment variables:
**`n3fips_password=:`**
Identifies a [crypto user](understanding-users-cmu.md#crypto-user-cmu) (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 [createUser](cloudhsm_mgmt_util-createUser.md). To find existing CUs, use [listUsers](cloudhsm_mgmt_util-listUsers.md).
For example:
```
setx /m n3fips_password test_user:password123
```
# Associate an AWS CloudHSM key with a certificate
Before you can use AWS CloudHSM keys with third-party tools, such as Microsoft's [SignTool](https://docs.microsoft.com/en-us/windows/win32/seccrypto/signtool), you must import the key's metadata into the local certificate store and associate the metadata with a certificate. To import the key's metadata, use the import\$1key.exe utility which is included in CloudHSM version 3.0 and higher. The following steps provide additional information, and sample output.
## Step 1: Import your certificate
On Windows, you should be able to double-click the certificate to import it to your local certificate store.
However, if double-clicking doesn't work, use the [Microsoft Certreq tool](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn296456%28v%3dws.11%29) to import the certificate into the certificate manager. For example:
```
certreq -accept
```
If this action fails and you receive the error, `Key not found`, continue to Step 2. If the certificate appears in your key store, you've completed the task and no further action is necessary.
## Step 2: Gather certificate-identifying information
If the previous step wasn't successful, you'll need to associate your private key with a certificate. However, before you can create the association, you must first find the certificate's Unique Container Name and Serial Number. Use a utility, such as **certutil**, to display the needed certificate information. The following sample output from **certutil** shows the container name and the serial number.
```
================ Certificate 1 ================ Serial Number:
72000000047f7f7a9d41851b4e000000000004Issuer: CN=Enterprise-CANotBefore: 10/8/2019 11:50
AM NotAfter: 11/8/2020 12:00 PMSubject: CN=www.example.com, OU=Certificate Management,
O=Information Technology, L=Seattle, S=Washington, C=USNon-root CertificateCert
Hash(sha1): 7f d8 5c 00 27 bf 37 74 3d 71 5b 54 4e c0 94 20 45 75 bc 65No key provider
information Simple container name: CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c Unique
container name: CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c
```
## Step 3: Associate the AWS CloudHSM private key with the certificate
To associate the key with the certificate, first be sure to [start the AWS CloudHSM client daemon](key_mgmt_util-setup.md#key_mgmt_util-start-cloudhsm-client). Then, use import\$1key.exe (which is included in CloudHSM version 3.0 and higher) to associate the private key with the certificate. When specifying the certificate, use its simple container name. The following example shows the command and the response. This action only copies the key's metadata; the key remains on the HSM.
```
$> import_key.exe –RSA CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c
Successfully opened Microsoft Software Key Storage Provider : 0NCryptOpenKey failed : 80090016
```
## Step 4: Update the certificate store
Be certain the AWS CloudHSM client daemon is still running. Then, use the **certutil** verb, **-repairstore**, to update the certificate serial number. The following sample shows the command and output. See the Microsoft documentation for information about the [**-repairstore** verb](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/cc732443(v=ws.11)?redirectedfrom=MSDN#-repairstore).
```
C:\Program Files\Amazon\CloudHSM>certutil -f -csp "Cavium Key Storage Provider"-repairstore my "72000000047f7f7a9d41851b4e000000000004"
my "Personal"
================ Certificate 1 ================
Serial Number: 72000000047f7f7a9d41851b4e000000000004
Issuer: CN=Enterprise-CA
NotBefore: 10/8/2019 11:50 AM
NotAfter: 11/8/2020 12:00 PM
Subject: CN=www.example.com, OU=Certificate Management, O=Information Technology, L=Seattle, S=Washington, C=US
Non-root CertificateCert Hash(sha1): 7f d8 5c 00 27 bf 37 74 3d 71 5b 54 4e c0 94 20 45 75 bc 65
SDK Version: 3.0
Key Container = CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c
Provider = "Cavium Key Storage Provider"
Private key is NOT exportableEncryption test passedCertUtil: -repairstore command completed successfully.
```
After updating the certificate serial number you can use this certificate and the corresponding AWS CloudHSM private key with any third-party signing tool on Windows.
# Code sample for CNG provider for AWS CloudHSM
****
\$1\$1 Example code only – Not for production use \$1\$1
This sample code is for illustrative purposes only. Do not run this code in production.
The following sample shows how to enumerate the registered cryptographic providers on your system to find the CNG provider installed with CloudHSM client for Windows. The sample also shows how to create an asymmetric key pair and how to use the key pair to sign data.
**Important**
Before you run this example, you must set up the HSM credentials as explained in the prerequisites. For details, see [Prerequisites for using the AWS CloudHSM Windows Client](ksp-library-prereq.md).
```
// CloudHsmCngExampleConsole.cpp : Console application that demonstrates CNG capabilities.
// This example contains the following functions.
//
// VerifyProvider() - Enumerate the registered providers and retrieve Cavium KSP and CNG providers.
// GenerateKeyPair() - Create an RSA key pair.
// SignData() - Sign and verify data.
//
#include "stdafx.h"
#include
#ifndef NT_SUCCESS
#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
#endif
#define CAVIUM_CNG_PROVIDER L"Cavium CNG Provider"
#define CAVIUM_KEYSTORE_PROVIDER L"Cavium Key Storage Provider"
// Enumerate the registered providers and determine whether the Cavium CNG provider
// and the Cavium KSP provider exist.
//
bool VerifyProvider()
{
NTSTATUS status;
ULONG cbBuffer = 0;
PCRYPT_PROVIDERS pBuffer = NULL;
bool foundCng = false;
bool foundKeystore = false;
// Retrieve information about the registered providers.
// cbBuffer - the size, in bytes, of the buffer pointed to by pBuffer.
// pBuffer - pointer to a buffer that contains a CRYPT_PROVIDERS structure.
status = BCryptEnumRegisteredProviders(&cbBuffer, &pBuffer);
// If registered providers exist, enumerate them and determine whether the
// Cavium CNG provider and Cavium KSP provider have been registered.
if (NT_SUCCESS(status))
{
if (pBuffer != NULL)
{
for (ULONG i = 0; i < pBuffer->cProviders; i++)
{
// Determine whether the Cavium CNG provider exists.
if (wcscmp(CAVIUM_CNG_PROVIDER, pBuffer->rgpszProviders[i]) == 0)
{
printf("Found %S\n", CAVIUM_CNG_PROVIDER);
foundCng = true;
}
// Determine whether the Cavium KSP provider exists.
else if (wcscmp(CAVIUM_KEYSTORE_PROVIDER, pBuffer->rgpszProviders[i]) == 0)
{
printf("Found %S\n", CAVIUM_KEYSTORE_PROVIDER);
foundKeystore = true;
}
}
}
}
else
{
printf("BCryptEnumRegisteredProviders failed with error code 0x%08x\n", status);
}
// Free memory allocated for the CRYPT_PROVIDERS structure.
if (NULL != pBuffer)
{
BCryptFreeBuffer(pBuffer);
}
return foundCng == foundKeystore == true;
}
// Generate an asymmetric key pair. As used here, this example generates an RSA key pair
// and returns a handle. The handle is used in subsequent operations that use the key pair.
// The key material is not available.
//
// The key pair is used in the SignData function.
//
NTSTATUS GenerateKeyPair(BCRYPT_ALG_HANDLE hAlgorithm, BCRYPT_KEY_HANDLE *hKey)
{
NTSTATUS status;
// Generate the key pair.
status = BCryptGenerateKeyPair(hAlgorithm, hKey, 2048, 0);
if (!NT_SUCCESS(status))
{
printf("BCryptGenerateKeyPair failed with code 0x%08x\n", status);
return status;
}
// Finalize the key pair. The public/private key pair cannot be used until this
// function is called.
status = BCryptFinalizeKeyPair(*hKey, 0);
if (!NT_SUCCESS(status))
{
printf("BCryptFinalizeKeyPair failed with code 0x%08x\n", status);
return status;
}
return status;
}
// Sign and verify data using the RSA key pair. The data in this function is hardcoded
// and is for example purposes only.
//
NTSTATUS SignData(BCRYPT_KEY_HANDLE hKey)
{
NTSTATUS status;
PBYTE sig;
ULONG sigLen;
ULONG resLen;
BCRYPT_PKCS1_PADDING_INFO pInfo;
// Hardcode the data to be signed (for demonstration purposes only).
PBYTE message = (PBYTE)"d83e7716bed8a20343d8dc6845e57447";
ULONG messageLen = strlen((char*)message);
// Retrieve the size of the buffer needed for the signature.
status = BCryptSignHash(hKey, NULL, message, messageLen, NULL, 0, &sigLen, 0);
if (!NT_SUCCESS(status))
{
printf("BCryptSignHash failed with code 0x%08x\n", status);
return status;
}
// Allocate a buffer for the signature.
sig = (PBYTE)HeapAlloc(GetProcessHeap(), 0, sigLen);
if (sig == NULL)
{
return -1;
}
// Use the SHA256 algorithm to create padding information.
pInfo.pszAlgId = BCRYPT_SHA256_ALGORITHM;
// Create a signature.
status = BCryptSignHash(hKey, &pInfo, message, messageLen, sig, sigLen, &resLen, BCRYPT_PAD_PKCS1);
if (!NT_SUCCESS(status))
{
printf("BCryptSignHash failed with code 0x%08x\n", status);
return status;
}
// Verify the signature.
status = BCryptVerifySignature(hKey, &pInfo, message, messageLen, sig, sigLen, BCRYPT_PAD_PKCS1);
if (!NT_SUCCESS(status))
{
printf("BCryptVerifySignature failed with code 0x%08x\n", status);
return status;
}
// Free the memory allocated for the signature.
if (sig != NULL)
{
HeapFree(GetProcessHeap(), 0, sig);
sig = NULL;
}
return 0;
}
// Main function.
//
int main()
{
NTSTATUS status;
BCRYPT_ALG_HANDLE hRsaAlg;
BCRYPT_KEY_HANDLE hKey = NULL;
// Enumerate the registered providers.
printf("Searching for Cavium providers...\n");
if (VerifyProvider() == false) {
printf("Could not find the CNG and Keystore providers\n");
return 1;
}
// Get the RSA algorithm provider from the Cavium CNG provider.
printf("Opening RSA algorithm\n");
status = BCryptOpenAlgorithmProvider(&hRsaAlg, BCRYPT_RSA_ALGORITHM, CAVIUM_CNG_PROVIDER, 0);
if (!NT_SUCCESS(status))
{
printf("BCryptOpenAlgorithmProvider RSA failed with code 0x%08x\n", status);
return status;
}
// Generate an asymmetric key pair using the RSA algorithm.
printf("Generating RSA Keypair\n");
GenerateKeyPair(hRsaAlg, &hKey);
if (hKey == NULL)
{
printf("Invalid key handle returned\n");
return 0;
}
printf("Done!\n");
// Sign and verify [hardcoded] data using the RSA key pair.
printf("Sign/Verify data with key\n");
SignData(hKey);
printf("Done!\n");
// Remove the key handle from memory.
status = BCryptDestroyKey(hKey);
if (!NT_SUCCESS(status))
{
printf("BCryptDestroyKey failed with code 0x%08x\n", status);
return status;
}
// Close the RSA algorithm provider.
status = BCryptCloseAlgorithmProvider(hRsaAlg, NULL);
if (!NT_SUCCESS(status))
{
printf("BCryptCloseAlgorithmProvider RSA failed with code 0x%08x\n", status);
return status;
}
return 0;
}
```