Microsoft Azure Key Vault BYOK

1Set up Luna HSM

2Set required partition policies

3Download HSM BYOK tool

4Install Microsoft Azure CLI

5Obtain Azure Key Vault premium subscription

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 Microsoft Azure Key Vault BYOK.

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:

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

Note

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

1Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means

2Extract the .zip file into a directory on your client workstation.

3Extract 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

4Run 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.

Note

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

5Run the LunaCM utility and verify that the Cloud HSM service is listed.

1Private Key Cloning: OFF

• This prevents the Tenant key from being cloned.

• Setting: 0: Allow private key cloning: 0

2Private Key Wrapping: ON

• This allows the Tenant key to be securely wrapped.

• Setting: 1: Allow private key wrapping: 1

3Secret Key Wrapping: ON

• Enables wrapping of the AES key generated by the BYOK utility.

• Setting: 5: Allow secret key wrapping: 1

4CBC-PAD (un)wrap: ON

• Allows padding for wrapping and unwrapping keys.

• Setting: 34: Allow CBC-PAD (un)wrap keys of any size: 1

5Multipurpose 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

1Generate Key Exchange Key

2Download KEK public key

3Generate and prepare your tenant key

4Transfer the tenant key to Azure Key Vault

1Ensure 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".

2Open 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.

3Create 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.

4Create 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.

5Generate 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).

6After 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.

1Open PowerShell on your workstation.

2Run 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).

Note

The KEK public key will be saved in the specified PEM file after the command executes successfully.

1Extract 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.

2Place the downloaded PEM file into the directory where you extracted the BYOK tool.

3Rename 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

Note

Ensure both the BYOK utility and the kekBlob.pem file are in the same directory for proper operation.

4In 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 the targetKeySpec, define the key specifications as follows: For RSA keys, use CKK_RSA, 2048, none. For EC keys, use CKK_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.

Note

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.

5Execute 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"
}

1Use 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

Note

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.

2Use 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

Note

The imported tenant key will also be visible in the Azure Key Vault under Settings > Keys.