Microsoft Azure Key Vault BYOK
This document offers detailed guidance on integrating Microsoft Azure Key Vault BYOK with Luna HSM devices or Luna Cloud HSM services. To effectively utilize this guide, a basic understanding of Microsoft Azure Key Vault BYOK and Luna HSM concepts is required.
Integrating Microsoft Azure Key Vault with Thales Luna HSMs offers a robust solution for managing your cryptographic keys securely in the cloud. Azure Key Vault acts as a central hub for creating, storing, and managing your keys, while the Thales Luna HSMs add an extra layer of security by keeping these keys safe in a tamper-resistant hardware environment. This setup not only strengthens your security but also ensures compliance with regulations and gives you greater control over your keys throughout their lifecycle. By using this integration, you can confidently protect sensitive data, maintain strict access controls, and minimize risks like unauthorized access. It's an ideal solution for hybrid cloud environments, simplifying key management while enhancing security.
The benefits of integrating Luna HSMs with Microsoft Azure Key Vault BYOK include:
-
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 HSM Devices
This integration is compatible with a range of Thales Luna HSM devices, ensuring flexibility for your security needs:
-
Thales Luna Network HSM 7 (Firmware 7.3 and above)
-
Thales Luna PCIe HSM 7 (Firmware 7.3 and above)
-
Thales Luna U700 USB HSM
-
Luna Cloud HSM
This compatibility ensures that whether you are working on-premises or in the cloud, you have access to secure, compliant, and efficient key management solutions.
Prerequisites
Before integrating, ensure that the following prerequisites are met:
Set up Luna HSM
As the first step to accomplish this integration, you need to set up either On-Premise Luna HSM or Luna Cloud HSM.
Set up On-Premise Luna HSM
Follow these steps to set up your on-premise Luna HSM:
Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
Create a partition that will be later on used by Microsoft Azure Key Vault BYOK.
Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
Initialize Crypto Officer and Crypto User roles for the registered partition.
Run the following command to verify that the partition has been successfully registered and configured:
C:\Program Files\SafeNet\LunaClient>lunacm.exe
Upon successful execution, you should observe an output similar to the example provided below:
lunacm.exe (64-bit) v10.1.0-32. Copyright (c) 2019 SafeNet. All rights reserved. Available HSMs: Slot Id -> 0 Label -> bok Serial Number -> 131209861410 Model -> LunaSA 7.4.0 Firmware Version -> 7.4.0 Configuration -> Luna User Partition With SO (PW) Signing With Cloning Mode Slot Description -> Net Token Slot FM HW Status -> Non-FM Current Slot Id: 0
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
Set up Luna HSM in FIPS Mode
To configure Luna HSM in FIPS Mode, update the configuration file by adding or modifying the following setting within the [Misc]
section:
RSAKeyGenMechRemap=1
This setting ensures that older calling mechanisms are redirected to the approved RSA key generation methods (186-3 with primes and 186-3 with aux primes) required for FIPS compliance. By making this configuration change, Luna HSM will be properly set up to operate in FIPS mode, adhering to the approved RSA key generation standards.
The configuration setting mentioned above, RSAKeyGenMechRemap=1
, is not required for the Universal Client. It is applicable only for Luna Client 7.x.
Set up Luna Cloud HSM
The following steps are applicable for setting up the Luna Cloud HSM on a Windows environment:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means
Extract the .zip file into a directory on your client workstation.
Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.
cvclient-min.zip
Run the setenv
script to generate a new configuration file with the necessary information for the Luna Cloud HSM service. Right-click setenv.cmd
and select Run as Administrator.
To add the configuration to an already installed UC client, use the –addcloudhsm
option when running the setenv
script.
Run the LunaCM utility and verify that the Cloud HSM service is listed.
If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.
Set required partition policies
Before starting the Azure BYOK process, make sure these settings are configured for your HSM partition:
Private Key Cloning: OFF
-
This prevents the Tenant key from being cloned.
-
Setting:
0: Allow private key cloning: 0
Private Key Wrapping: ON
-
This allows the Tenant key to be securely wrapped.
-
Setting:
1: Allow private key wrapping: 1
Secret Key Wrapping: ON
-
Enables wrapping of the AES key generated by the BYOK utility.
-
Setting:
5: Allow secret key wrapping: 1
CBC-PAD (un)wrap: ON
-
Allows padding for wrapping and unwrapping keys.
-
Setting:
34: Allow CBC-PAD (un)wrap keys of any size: 1
Multipurpose Key Policy: Optional
-
Turn this ON if you need multipurpose keys (e.g., keys that can Encrypt/Decrypt, Sign/Verify, or Derive). If OFF, the key will have a single purpose.
-
Setting:
10: Allow multipurpose keys: 1
Make sure all these policies are correctly configured to successfully generate and wrap the Tenant Key with the BYOK utility.
Download HSM BYOK tool
Thales provides the hsmbyok utility to streamline the export and import of tenant keys. This tool can be downloaded from the Thales Customer Support portal.
Resources:
-
KB Article: KB0021016 (for detailed instructions on the Luna 7 HSM BYOK utility)
-
DOW ID: DOW0004730 (for downloading the utility)
Install Microsoft Azure CLI
You need to install the Microsoft Azure CLI to execute the required commands in this guide. Ensure that both the Microsoft Azure CLI and the Luna HSM client are installed in the same environment.
-
Download: Microsoft Azure CLI Installation Guide
-
Important requirement: Version 2.0.82 or newer is required for Azure Key Vault BYOK operations.
Obtain Azure Key Vault premium subscription
An Azure Key Vault Premium P2 subscription is necessary to use HSM-protected keys. This subscription level provides the HSM support required for Azure Key Vault.
Supported Key Types
This integration supports various key types with Thales Luna HSMs, allowing for flexible and secure key management. Below is an overview of the supported keys, including their names, types, sizes, and origins:
Key Name | Key Type | Key Size/Curve | Origin | Description |
---|---|---|---|---|
Key Exchange Key (KEK) | RSA-HSM | 2,048-bit, 3,072-bit, 4,096-bit | Azure Key Vault (Managed HSM) | HSM-backed RSA key pair generated in Managed HSM |
Target Key (Tenant Key) | RSA-HSM | 2,048-bit, 3,072-bit, 4,096-bit | Luna HSM | Key generated on Luna HSM and transferred to Managed HSM |
Target Key (Tenant Key) | EC-HSM | P-256, P-384, P-521 | Luna HSM | Elliptic curve key generated on Luna HSM and transferred to Managed HSM |
Generate and transfer tenant key to Azure Key Vault
The process of generating and transferring your tenant key involves several key stages. Follow the steps below to ensure a secure and smooth transfer from the Luna HSM to the Azure Key Vault Managed HSM:
Generate Key Exchange Key
Start by generating the Key Exchange Key (KEK) on the Azure Key Vault Managed HSM. The Key Exchange Key (KEK) is an RSA key that will be used to securely transfer your tenant key to the Azure Key Vault Managed HSM. Follow these steps to generate the KEK:
Ensure KEK compliance:
-
The KEK must be an RSA-HSM key with encryption options of 2048-bit, 3072-bit, or 4096-bit.
-
It needs to be generated within the same Managed HSM in the Key Vault where the tenant key will be imported.
-
The key operation for the KEK must be set to "import".
Open PowerShell on your workstation. Ensure both the Luna Client and Azure CLI are installed and operational. Log in to the Azure portal using the following command:
az login
Provide your Azure credentials when prompted.
Create a resource group for the Azure Key Vault setup. Use this command:
az group create --name "<resource_group>" --location "<location>"
Replace <resource_group>
with your desired resource group name and <location>
with the appropriate region. You can check available regions for the Key Vault here.
Create an Azure Key Vault with a premium SKU using the command below:
az keyvault create --location "<location>" --name "<key_vault>" --resource-group "<resource_group>" --sku premium
Replace <key_vault>
and <resource_group>
with your specific names.
Generate the KEK within your Azure Key Vault. Set the key operations to "import" using this command:
az keyvault key create --name "<KEK_name>" --vault-name "<key_vault>" --kty RSA-HSM --size <key_size> --ops import
Replace <KEK_name>
with the name you want for your KEK, <key_vault>
with your Key Vault name, and <key_size>
with the desired key size (e.g., 2048, 3072, or 4096).
After successfully generating the KEK, take note of its unique key identifier, which will look something like this:
https://<your-keyvault>.vault.azure.net/keys/<KEK_name>/cdf405fb31414d4fb3b003d9dd5c4284
This identifier will be used in the subsequent steps to import the tenant key.
Download KEK public key
After generating the KEK, download its public key from the Azure Key Vault Managed HSM. This public key will be used to encrypt your tenant key during the transfer process. Follow these steps to obtain the public key in PEM format:
Open PowerShell on your workstation.
Run the following command to download the KEK public key from your Key Vault:
az keyvault key download --name <KEK_name> --vault-name <KeyVault_name> --file <KEK_publickey_filename>.pem
-
Replace
<KEK_name>
with the name of your Key Exchange Key (e.g., KEK2048-BYOK). -
Replace
<KeyVault_name>
with the name of your Azure Key Vault (e.g., MySafeNetKeyVault). -
Replace
<KEK_publickey_filename>
with the desired name for the downloaded file (e.g., KEK2048-BYOK.publickey).
The KEK public key will be saved in the specified PEM file after the command executes successfully.
Generate and prepare your tenant key
Next, generate your tenant key on the Luna HSM. Once the key is generated, it must be prepared for transfer by wrapping it with the KEK public key. To create and prepare your tenant key, follow these steps:
Extract the BYOK tool from the Thales Support Portal into a designated directory. Locate the hsmbyok
utility within the extracted folder. This utility will generate your tenant key and create a Key Transfer Package (BYOK file). It uses the key identifier and the PEM file from previous steps to generate the encrypted tenant key in BYOK format.
Place the downloaded PEM file into the directory where you extracted the BYOK tool.
Rename the PEM file to match the required name for the BYOK tool using the following command:
PS C:\BYOK> mv .\KEK2048-BYOK.publickey.pem .\kekBlob.pem
Ensure both the BYOK utility and the kekBlob.pem
file are in the same directory for proper operation.
In the same directory as the BYOK utility and the PEM file, create a file named HsmConfig.ini
with the following structure:
[ byok ]
; Cryptoki library path
libraryName = "C:\Program Files\SafeNet\LunaClient\cryptoki.dll"
; Partition label
tokenLabel = "byok"
; Available wrapping ciphers
wrappingCiphers = CKG_MGF1_SHA1, CKM_AES_KWP
; Key label for finding or generating
targetKeyName = "my-target-key-rsa2048"
; Key generation details
targetKeySpec = CKK_RSA, 2048, none
targetKeyFlags = CKF_ENCRYPT, CKF_DECRYPT, CKF_SIGN, CKF_VERIFY, CKF_DERIVE, CKF_TOKEN, CKF_MODIFIABLE, CKF_EXTRACTABLE, CKF_CREATE_IF_NOT_FOUND
; Azure Key Identifier
kid = "https://mysafenetkeyvault.vault.azure.net/keys/KEK2048-BYOK/cdf405fb31414d4fb3b003d9dd5c4284"
; Azure schema version
SchemaVersion = "1.0.0.0"
Important Details:
-
tokenLabel
: Represents your HSM partition label. -
targetKeyName
: The name of the key to be generated if it does not already exist. -
kid
: Refers to the key identifier from a previous step. -
targetKeySpec
: To specify thetargetKeySpec
, define the key specifications as follows: For RSA keys, useCKK_RSA, 2048, none
. For EC keys, useCKK_EC, 384, "P-384"
. When working with EC keys, you can choose from the following curve names: "X9_62_prime256v1" for P-256, "secp384r1" for P-384, and "secp521r1" for P-521.
If Policy 10 is off, the target key will be a single-purpose key. In this case, you should use only one of the following attributes for targetKeyFlags
, in addition to CKF_TOKEN
, CKF_MODIFIABLE
, CKF_EXTRACTABLE
, and CKF_CREATE_IF_NOT_FOUND
: CKF_ENCRYPT
or CKF_DECRYPT
, CKF_SIGN
or CKF_VERIFY
, or CKF_DERIVE
.
Execute the hsmbyok
utility to create the Key Transfer Package (BYOK file) by running the following command:
PS C:\BYOK> .\hsmbyok.exe --generate-and-wrap-target-key
This command will generate a file named targetBlob.byok
in JSON format. The contents of the file will be structured as follows:
{
"schema_version": "1.0.0",
"header": {
"kid": "<key identifier of the KEK>",
"alg": "dir",
"enc": "CKM_RSA_AES_KEY_WRAP"
},
"ciphertext": "BASE64URL(<ciphertext contents>)",
"generator": "byok tool name and version; source HSM name and firmware version"
}
Transfer the tenant key to Azure Key Vault
Finally, transfer the wrapped tenant key to the Azure Key Vault Managed HSM. This step completes the migration, ensuring that your key is securely housed in the cloud while maintaining the hardware security protections offered by the Luna HSM. To complete the transfer of your tenant key to Azure Key Vault, follow these steps:
Use the az keyvault key import
command to upload the targetBlob.byok
file created in the previous steps.
For RSA Keys:
PS C:\BYOK> az keyvault key import --vault-name MySafeNetKeyVault --name SafeNetRSA2048HSMkey --byok-file .\targetBlob.byok --protection hsm
In this command, SafeNetRSA2048HSMkey
is the name of your RSA tenant key being imported into the Azure HSM Key Vault.
For EC Keys:
PS C:\BYOK> az keyvault key import --vault-name MySafeNetKeyVault --name SafeNetEC256HSMkey --byok-file .\targetBlob.byok --kty EC --curve "P-256" --protection hsm
For EC keys, include the --kty EC --curve
parameters with the appropriate curve value. This is not necessary for RSA keys, as it is the default key type.
Use the az keyvault key show
command to display the details of the imported tenant key.
PS C:\BYOK> az keyvault key show --vault-name MySafeNetKeyVault --name SafeNetRSA2048HSMKey
The imported tenant key will also be visible in the Azure Key Vault under Settings > Keys.