Supported mechanisms for the PKCS #11 library
The PKCS #11 library is compliant with version 2.40 of the PKCS #11 specification. To invoke a cryptographic feature using PKCS #11, call a function with a given mechanism. The following sections summarize the combinations of functions and mechanisms supported by AWS CloudHSM.
The PKCS #11 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 Wrap1, AES-GCM, RSA-AES, and RSA-OAEP
Topics
Generate key and key pair functions
The AWS CloudHSM software library for PKCS #11 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 theCKM_RSA_PKCS_KEY_PAIR_GENmechanism, but offers stronger guarantees forpandqgeneration. -
CKM_EC_KEY_PAIR_GEN -
CKM_GENERIC_SECRET_KEY_GEN -
CKM_AES_KEY_GEN -
CKM_DES3_KEY_GEN– upcoming change listed in footnote 5.
Sign and verify functions
The AWS CloudHSM software library for PKCS #11 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 for more info.
RSA
CKM_RSA_X_509CKM_RSA_PKCS– single-part operations only.CKM_RSA_PKCS_PSS– single-part operations only.CKM_SHA1_RSA_PKCSCKM_SHA224_RSA_PKCSCKM_SHA256_RSA_PKCSCKM_SHA384_RSA_PKCSCKM_SHA512_RSA_PKCSCKM_SHA512_RSA_PKCSCKM_SHA1_RSA_PKCS_PSSCKM_SHA224_RSA_PKCS_PSSCKM_SHA256_RSA_PKCS_PSSCKM_SHA384_RSA_PKCS_PSSCKM_SHA512_RSA_PKCS_PSS
ECDSA
CKM_ECDSA– single-part operations only.CKM_ECDSA_SHA1CKM_ECDSA_SHA224CKM_ECDSA_SHA256CKM_ECDSA_SHA384CKM_ECDSA_SHA512
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 #11 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 #11 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. -
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. -
CKM_DES3_ECB– upcoming change listed in footnote 5. -
CKM_DES3_CBC_PAD– upcoming change listed in footnote 5. CKM_CLOUDHSM_AES_GCM3
Derive key functions
The AWS CloudHSM software library for PKCS #11 library allows you to use the following mechanisms for Derive functions.
-
CKM_SP800_108_COUNTER_KDF
Wrap and Unwrap functions
The AWS CloudHSM software library for PKCS #11 library allows you to use the following mechanisms for Wrap and Unwrap functions.
For additional information regarding AES key wrapping, see AES Key Wrapping.
Maximum data size for each mechanism
The following table lists the maximum data size set for each mechanism:
Maximum data set size | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Mechanism | Maximum data size in bytes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_SHA_1_HMAC |
16288 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_SHA224_HMAC |
16256 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_SHA256_HMAC |
16288 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_SHA384_HMAC |
16224 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_SHA512_HMAC |
16224 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_AES_CBC |
16272 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_AES_GCM |
16224 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_CLOUDHSM_AES_GCM |
16224 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CKM_DES3_CBC |
16280 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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_PARAMSparameters structure that you supply. To prevent user confusion, PKCS #11 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.
-
[3] Vendor-defined mechanism. In order to use the CloudHSM vendor defined mechanisms, PKCS#11 applications must include
/opt/cloudhsm/include/pkcs11t.hduring compilation.CKM_CLOUDHSM_AES_GCM: This proprietary mechanism is a programmatically safer alternative to the standardCKM_AES_GCM. It prepends the IV generated by the HSM to the ciphertext instead of writing it back into theCK_GCM_PARAMSstructure that is provided during cipher initialization. You can use this mechanism withC_Encrypt,C_WrapKey,C_Decrypt, andC_UnwrapKeyfunctions. When using this mechanism, the pIV variable in theCK_GCM_PARAMSstruct must be set toNULL. When using this mechanism withC_DecryptandC_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 #5 Padding.CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD: AES Key Wrap with Zero Padding. [4] The following
CK_MECHANISM_TYPEandCK_RSA_PKCS_MGF_TYPEare supported asCK_RSA_PKCS_OAEP_PARAMSforCKM_RSA_PKCS_OAEP:-
CKM_SHA_1usingCKG_MGF1_SHA1 -
CKM_SHA224usingCKG_MGF1_SHA224 -
CKM_SHA256usingCKG_MGF1_SHA256 -
CKM_SHA384usingCKM_MGF1_SHA384 -
CKM_SHA512usingCKM_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 for details.
