AWS Key Management Services
This guide provides detailed instructions for integrating AWS Key Management Service (KMS) with Luna HSM, covering installation, configuration, and key management. The AWS Bring Your Own Key (BYOK) solution enables customers to generate AES-256 keys within Luna HSM and securely export them to AWS KMS. During the export, an AWS-provided public key (wrapping key) encrypts the AES-256 key before transfer. To enable export, the key must be created with the exportable attribute set to true. If exporting an existing key, it must either have the exportable attribute set to true or be modifiable, ensuring compliance with AWS KMS import requirements.
This integration delivers the following benefits:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported key wrapping algorithms
Key wrapping algorithms protect cryptographic keys during transfer. Supported options include:
-
RSAES-PKCS1-v1_5 – Legacy RSA encryption, not recommended for new integrations.
-
RSAES-OAEP-SHA-1 – Uses OAEP with SHA-1; upgrading to SHA-256 is advised.
-
RSAES-OAEP-SHA-256 – Preferred for its enhanced security and adoption.
Note
For optimal security, choose RSAES-OAEP-SHA-256, ensuring compatibility with your HSM or key management system.
Prerequisites
To proceed with this integration:
Set up Luna HSM
Follow these steps to set up your on-premise Luna HSM:
1Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
2Create a partition that will be later on used by AWS KMS.
3Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
4Initialize Crypto Officer and Crypto User roles for the registered partition.
5Run the following command to verify that the partition has been successfully registered and configured:
/usr/safenet/lunaclient/bin/lunacm
Upon successful execution, you should observe an output similar to the example provided below:
lunacm.exe (64-bit) v10.7.1-125. Copyright (c) 2024 Thales Group. All rights reserved. Available HSMs: Slot Id -> 0 Label -> kms Serial Number -> 1280780175949 Model -> LunaSA 7.3.0 Firmware Version -> 7.3.0 Configuration -> Luna User Partition With SO (PW) Key Export With Cloning Mode Slot Description -> Net Token Slot Current Slot Id: 0
6For PED-authenticated HSMs, enable Partition Policies 22 and 23 to support activation and auto-activation.
Note
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
Access AWS Key Management Services
To use AWS KMS, ensure you have an AWS account and the necessary credentials for authentication.
Integrating AWS Key Management Services with Luna HSM
Integrating AWS KMS with Luna HSM involves these steps:
1Create a wrapping key and import token from AWS KMS
2Import the wrapping key into Luna HSM
3Generate encrypted key material using the imported wrapping key
Create a wrapping key and import token from AWS KMS
Follow these steps to create the wrapping key and import token:
1Sign in to the AWS Console at https://aws.amazon.com.
2Navigate to IAM under Security, Identity & Compliance.
3Select Users, then click Add User. Enter a User Name, select Programmatic access under Access type, and click Next: Permissions.
4Choose Attach existing policies directly, select AdministratorAccess, and click Next: Tags (optional).
5Click Next: Review, then Create user. This IAM user will later be assigned permissions for the Master Key.
6Go to Key Management Service (KMS) and select Create key.
7Choose Symmetric as the key type.
8Click Advanced Options, select External for Key Material Origin, check the acknowledgment box, and click Next.
9Enter a Key Alias and Description. Optionally, add Tags, then click Next.
10On the Define Key Administrative Permissions page, select the IAM user to manage the key and check Allow key administrators to delete this key, then click Next.
11On the Define Key Usage Permissions page, select the IAM user created earlier and click Next.
12Review the key policy on the Preview Key Policy page, then click Finish.
13On the Download Wrapping Key and Import Token page, select a Wrapping Algorithm from the dropdown and click Download Wrapping Key and Import Token to save the ImportParameters.zip file.
14Extract ImportParameters.zip to access the wrapping key (RSA Public Key) and import token. Import the wrapping key into the HSM.
Import the wrapping key into Luna HSM
Follow these steps to import the wrapping key into Luna HSM:
1Convert the wrapping key to PEM format using OpenSSL:
openssl rsa -in wrappingKey_f046d05f-6944-411b-958a-928e0215a1a2_0426062751 -inform DER -out pub_key.pem -outform PEM -pubin -pubout
This command converts the key and saves the public key in pub_key.pem
.
2Import the public key into the HSM using the CMU utility:
./cmu import -inputfile=pub_key.pem -pubkey=pub_key.pem -label "AWS Public Key"
When prompted, enter the HSM partition password
.
3Verify that the key has been imported successfully:
./cmu list
Enter the HSM partition password
again and verify that the key appears in the list, such as: handle=228 label=AWS Public Key
. Make a note of the handle
for future use.
4Verify that the public key attributes (Encrypt, Verify, Wrap) are set to true:
./cmu getattribute -handle=228
When prompted, enter the HSM partition password
. Check the output to ensure the attributes encrypt
, wrap
, and verify
are set to true
.
5If the attributes are not set to true, update them using the following command:
./cmu setattribute -handle=228 -wrap=True -encrypt=True
Enter the HSM partition password
when prompted. Ensure the correct handle
is used for the public key.
Generate encrypted key material using the imported wrapping key
Follow these steps to generate an AES-256 key on the HSM for AWS KMS:
1Launch CKDemo and authenticate:
- Run the CKDemo utility:
ckdemo
- Select
(1) Open Session
and enter:
Enter your choice: 1
- Select
(3) Login
, chooseCrypto Officer (1)
, and enter the partition PIN.
2Generate an AES-256 key:
-
Select
(45) Simple Generate Key
from the main menu. -
Choose
AES (16)
when prompted for the key type. -
Set the key length to
32 bytes
(256 bits). -
Set the following attributes to
1 (True)
to enable full cryptographic functionality: Token, Sensitive, Private, Modifiable, Encrypt, Decrypt, Sign, Verify, Wrap, Unwrap, Derive, and Extractable. -
After confirmation, the system generates a key and displays its handle:
Generated AES Key: 231 (0x000000e7)
Note
Save this handle for later steps.
3Modify OAEP Hash Algorithm (If Using RSAES_OAEP):
Note
Skip this step if using RSAES_PKCS1_V1_5
as the wrapping key algorithm.
- Open CKDemo options:
ckdemo
- Select
(98) Options
:
Enter your choice: 98
- The following options will be displayed:
1 - Open Session Type : Always R/W and Serial 2 - Display Help : Always 3 - PIN path : user supplies ASCII password 4 - Echo input : Disabled 5 - Sleep for n seconds after writing special instructions to stderr 6 - KCV Default : user supplies KCV Domain 7 - MofN path : user supplies MofN path 8 - Show Response Code : SHOW_RESPONSE_BEFORE_AND_AFTER_MENU 9 - Input data for sign/derive : input from keyboard 10 - Object Usage Counters : disabled 11 - GCM IV Source : external 12 - ECIES Parameters : use default (XOR with HMAC_SHA1) 13 - X9.31 Signatures : allow X9.31 generated keys only 14 - Multipart enc/dec/sig/ver : use single part operations 15 - Use Old Enc/Dec Menu : use old menu 16 - Role Support : enhanced roles 17 - OAEP Hash Params : use default (SHA1 Digest and MGF1) 18 - Array Template Attributes : use array template attributes 19 - Specify Number of Objects Handles to Find per Update call? : No 20 - Specify Number of Objects to Create/Keys to generate? : No 21 - Prompt for CKA_CHECK_VALUE during key unwrap/derive? : No 0 - Finished
-
Locate
(17) OAEP Hash Params
, which defaults toSHA1 Digest and MGF1
. -
Change it to
selectable
by entering:
Enter option to change: 17
- The updated configuration will display:
17 - OAEP Hash Params : selectable
- Save and exit:
Enter option to change: 0
4Wrap the AES-256 Key:
Note
The AES-256 key must be wrapped using the public key downloaded from the AWS KMS console
.
- In the same CKDemo session, select
(60) Wrap Key
:
Enter your choice: 60
- Select
(26) RSA_OAEP
as the wrapping mechanism:
Select mechanism for wrapping: 26
Note
If using RSAES_PKCS1_V1_5
, select (9) RSA
instead.
- Choose the OAEP hash function:
Mechanism to use: [1]SHA-1 [2]SHA224 [3]SHA256 [4]SHA384 [5]SHA512 : 3
Note
Choose (3) SHA256
for RSAES_OAEP_SHA_256
. Select (1) SHA-1
for RSAES_OAEP_SHA_1
.
- When prompted, enter
0
for OAEP source data:
Enter filename of OAEP Source Data [0 for none]: 0
- Provide the
wrapping key handle (public key)
:
Enter handle of wrapping key (0 to list available objects): 228
- Provide the
AES-256 key handle
:
Enter handle of key to wrap (0 to list available objects): 231
- The wrapped key will be saved as:
Wrapped key was saved in file wrapped.key
Note
wrapped.key
contains the encrypted AES-256 key. This file must be securely transferred to AWS KMS for further use.
5Exit the session by selecting (0) Finished
:
Enter your choice: 0
Upload the encrypted key material to AWS KMS for use
After generating the encrypted key material, follow these steps to upload it to AWS KMS.
1Open the AWS KMS console:
- If you are still on the Import Key Material page, select I am ready to upload my exported key material, then click Next.
OR
-
Navigate to Customer managed keys and select the Key ID or alias of the CMK for which you downloaded the wrapping key and import token.
-
Under the Key material section, click Upload Key Material.
2Upload the encrypted key material and import token:
-
In the Specify key material details section, click Choose file next to Encrypted key material and select the wrapped AES key file.
-
Click Choose file next to Import token and select the importToken file.
3In the Choose an expiration option section:
-
Select Key material does not expire.
-
Click Finish to complete the upload.
4Verify the import:
-
A confirmation message will appear indicating the key was successfully imported.
-
The key will now be listed under Encryption keys, with the status set to Enabled.