This topic describes the options for AES key wrapping in AWS CloudHSM. AES key wrapping uses an AES key (the wrapping key) to wrap another key of any type (the target key). You use key wrapping to protect stored keys or transmit keys over insecure networks.
Supported algorithms
AWS CloudHSM offers three options for AES key wrapping, each based on how the target key is padded before being wrapped. Padding is done automatically, in accordance with the algorithm you use, when you call key wrap. The following table lists the supported algorithms and associated details to help you choose an appropriate wrapping mechanism for your application.
| AES Key Wrap Algorithm | Specification | Supported Target Key Types | Padding Scheme | AWS CloudHSM Client Availability |
|---|---|---|---|---|
| AES Key Wrap with Zero Padding | RFC 5649 |
All | Adds zeros after key bits, if necessary, to block align | SDK 3.1 and later |
| AES Key Wrap with No Padding | RFC 3394 |
Block-aligned keys such as AES and 3DES | None | SDK 3.1 and later |
| AES Key Wrap with PKCS #5 Padding | None | All |
At least 8 bytes are added as per PKCS #5 padding scheme to block align |
All |
To learn how to use the AES key wrap algorithms from the preceding table in your application, see Using AES Key Wrap in AWS CloudHSM.
Understanding initialization vectors in AES key wrap
Prior to wrapping, CloudHSM appends an initialization vector (IV) to the target key for data integrity. Each key wrap algorithm has specific restrictions on what type of IV is allowed. To set the IV in AWS CloudHSM, you have two options:
-
Implicit: set the IV to NULL and CloudHSM uses the default value for that algorithm for wrap and unwrap operations (recommended)
-
Explicit: set the IV by passing the default IV value to the key wrap function
Important
You must understand what IV you are using in your application. To unwrap the key, you must provide the same IV that you used to wrap the key. If you use an implicit IV to wrap, then use an implicit IV to unwrap. With an implicit IV, CloudHSM will use the default value to unwrap.
The following table describes permitted values for IVs, which the wrapping algorithm specifies.
| AES Key Wrap Algorithm | Implicit IV | Explicit IV |
|---|---|---|
| AES Key Wrap with Zero Padding | Required Default value: (IV calculated internally based on specification) |
Not allowed |
| AES Key Wrap with No Padding | Allowed (recommended) Default value:
|
Allowed Only this value accepted:
|
| AES Key Wrap with PKCS #5 Padding | Allowed (recommended) Default value:
|
Allowed Only this value accepted:
|
Using AES key wrap in AWS CloudHSM
You wrap and unwrap keys as follows:
-
In the PKCS #11 library, select the appropriate mechanism for the
C_WrapKeyandC_UnWrapKeyfunctions as shown in the following table. -
In the JCE provider, select the appropriate algorithm, mode and padding combination, implementing cipher methods
Cipher.WRAP_MODEandCipher.UNWRAP_MODEas shown in the following table. -
In the CloudHSM CLI, choose the appropriate algorithm from the list of supported The key wrap command in CloudHSM CLI and The key unwrap command in CloudHSM CLI algorithms as shown in the following table.
-
In key_mgmt_util (KMU), use commands Export an AWS CloudHSM key using KMU and Unwrap an AWS CloudHSM key using KMU with appropriate m values as shown in the following table.
| AES Key Wrap Algorithm | PKCS #11 Mechanism | Java Method | CloudHSM CLI Sub Command | Key Management Utility (KMU) Argument |
|---|---|---|---|---|
| AES Key Wrap with Zero Padding |
|
AESWrap/ECB/ZeroPadding |
aes-zero-pad | m = 6 |
| AES Key Wrap with No Padding |
|
AESWrap/ECB/NoPadding |
aes-no-pad | m = 5 |
| AES Key Wrap with PKCS #5 Padding |
|
AESWrap/ECB/PKCS5Padding |
aes-pkcs5-pad | m = 4 |
