Marvell Liquid Security HSM

Liquid Security HSM Adapters

Exporting Marvell HSM Keys to the Azure Key Vault

 

Overview

This page provides instructions for importing Marvell HSM-protected keys to the Azure Key Vault using the Marvell BYOK tool. The tool implements the new method defined by Azure.

 

Actions to Perform on Azure

  1. Create a Key Vault, if you do not already have one. The Key Vault must have a premium subscription and be in the West Central US location.
  2. In the Key Vault, generate an asymmetric key pair (the Key Exchange Key (KEK)). The KEK must be an RSA-HSM key with only the import key operation. Only the Key Vault Premium SKU supports RSA-HSM keys.
    Note: Currently, you cannot create this key using Azure Key Vault UI because the UI does not allow setting “import” permission. This limitation will go away when the feature is generally available. For now, use Azure CLI as follows:
    az keyvault key create
    -–kty RSA-HSM
    --size <2048, 3072, or 4096>
    --name <KEK name>
    --ops import
    --vault-name <Vault name>
    Make note of the following two pieces of information:
    KEK Key Identifier (Full URL)
    Key Vault name

 

 

Actions to Perform on Marvell HSM

 

Assumptions

  • SDK 3.3 has been built and installed on a CentOS 7x host. To verify the installation, look for the following install path: cnn35xx-nfbe-kvm-xen-pf/software/bindist. Then, under cnn35xx-nfbe-kvm-xen-pf/software/bindist, run the command:
    ./Cfm2MasterUtil -singleCmd getHSMInfo;
    The HSM information should display without any error. If there is an error, refer to the Marvell HSM SDK User Guide and fix any issues before proceeding.
  • BYOK user is familiar with SDK 3.3 commands using the utilities Cfm2MasterUtil and Cfm2Util.
  • Azure CLI for CentOS has been installed. See https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest

 

Preparing Your System

  1. Download the Marvell BYOK tool into the bindist folder where Cfm2MasterUtil and other utilities are installed. 
  2. Log in as  root and change to the cnn35xx-nfbe-kvm-xen-pf/software/bindist directory.
  3. Export the KEK public key from the Azure Key Vault.
    az keyvault key download
       --name <KEK name> 
       --vault-name <Vault name>
       --file <PEM file name>
  4. Import the KEK public key from the Azure Key Vault into the Marvell HSM.
    # ./Cfm2Util
    # loginHSM -u <user type> -p <password> -s <username>
    # importPubKey -l <Key label> -f <PEM file name path>
    Make note of the key handle value of the imported KEK public key.
  5. Find the private key handle value of the target key to be brought from the Marvell HSM into the Azure Key Vault.
    # ./Cfm2Util
    # loginHSM -u <user type> -p <password> -s <username>
    # findKey -l <Key label>
    Make note of the key handle value of the private key.

 

Running the Marvell BYOK Tool

You can run this tool from any machine that can reach your Marvell HSM cluster over a network. The tool performs the following actions:

  • Identifies the target RSA private key by its key handle value.
  • Generates the BYOK file that Azure uses to perform the import operation.
  • Performs the BYOK import operation using the generated BYOK file.

The tool takes the following arguments: 

Argument Description
-s Username of Partition Crypto User (PCU)
-p Password of PCU
-i  Key ID URL of Azure Key Vault 
-w Key Handle of Azure KEK Public Dey
-k Key Handle of Target Key RSA Private Key

The BYOK output file name is importing_target_key.byok.

Example:
.\Marvell_BYOK_Tool.sh -s pcu -p pcu1234
-i https://kv1-west.vault.azure.net/keys/mskek2048/118275477bd2454fbad778bcf3490645 -w 13 -k 7

 

Importing the BYOK File

To import the BYOK file into the Azure Key Vault, log in as root user and complete the following steps:

  1. Change the directory path to cnn35xx-nfbe-kvm-xen-pf/software/bindist, where the SDK 3.3 installed build is located
  2. Type az login and wait for the browser to launch. Enter your Azure credentials.
  3. Run the following command:

    az keyvault key import –name
                                             --vault-name
                                             [--byok-file]
                                             [--disabled {false, true}]
                                             [--expires]
                                             [--not-before]
                                             [--ops {decrypt, encrypt, import, sign, unwrapKey, verify, wrapKey}]
                                             [--pem-file]
                                             [--pem-password]
                                             [--protection {hsm, software}]
                                             [--subscription]
                                            [--tags]

    For example:

    az keyvault key import
    --name imported-key 
    --vault-name kv1-west
    --byok-file importing_target_key.byok

  4. Verify that the imported key is located in portal.azure.com.