# 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 } ```