Import HSM-protected keys to Managed HSM (BYOK)
Azure Key Vault Managed HSM supports importing keys generated in your on-premises hardware security module (HSM); the keys will never leave the HSM protection boundary. This scenario often is referred to as bring your own key (BYOK). Managed HSM uses the Marvell LiquidSecurity HSM adapters (FIPS 140-2 Level 3 validated) to protect your keys.
Use the information in this article to help you plan for, generate, and transfer your own HSM-protected keys to use with Managed HSM.
Note
This functionality is not available for Microsoft Azure operated by 21Vianet. This import method is available only for supported HSMs.
For more information, and for a tutorial to get started using Managed HSM, see What is Managed HSM?.
Overview
Here's an overview of the process. Specific steps to complete are described later in the article.
- In Managed HSM, generate a key (referred to as a Key Exchange Key (KEK)). The KEK must be an RSA-HSM key that has only the
importkey operation. - Download the KEK public key as a .pem file.
- Transfer the KEK public key to an offline computer that is connected to an on-premises HSM.
- In the offline computer, use the BYOK tool provided by your HSM vendor to create a BYOK file.
- The target key is encrypted with a KEK, which stays encrypted until it's transferred to the Managed HSM. Only the encrypted version of your key leaves the on-premises HSM.
- A KEK that's generated inside a Managed HSM isn't exportable. HSMs enforce the rule that no clear version of a KEK exists outside a Managed HSM.
- The KEK must be in the same managed HSM where the target key will be imported.
- When the BYOK file is uploaded to Managed HSM, a Managed HSM uses the KEK private key to decrypt the target key material and import it as an HSM key. This operation happens entirely inside the HSM. The target key always remains in the HSM protection boundary.
Prerequisites
To use the Azure CLI commands in this article, you must have the following items:
- A subscription to Microsoft Azure. If you don't have one, you can sign up for a free trial.
- The Azure CLI version 2.12.0 or later. Run
az --versionto find the version. If you need to install or upgrade, see Install the Azure CLI. - A managed HSM the supported HSMs list in your subscription. See Quickstart: Provision and activate a managed HSM using Azure CLI to provision and activate a managed HSM.
Azure Cloud Shell
Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.
To start Azure Cloud Shell:
| Option | Example/Link |
|---|---|
| Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell. |  |
| Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. |  |
| Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. |  |
To use Azure Cloud Shell:
Start Cloud Shell.
Select the Copy button on a code block (or command block) to copy the code or command.
Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.
Select Enter to run the code or command.
To sign in to Azure using the CLI, type:
az login
For more information on login options via the CLI, take a look at sign in with Azure CLI
Supported HSMs
| Vendor name | Vendor Type | Supported HSM models | More information |
|---|---|---|---|
| Cryptomathic | ISV (Enterprise Key Management System) | Multiple HSM brands and models including
|
|
| Entrust | Manufacturer, HSM as a service |
|
nCipher new BYOK tool and documentation |
| Fortanix | Manufacturer, HSM as a service |
|
Exporting SDKMS keys to Cloud Providers for BYOK - Azure Key Vault |
| IBM | Manufacturer | IBM 476x, CryptoExpress | IBM Enterprise Key Management Foundation |
| Marvell | Manufacturer | All LiquidSecurity HSMs with
|
Marvell BYOK tool and documentation |
| Securosys SA | Manufacturer, HSM as a service | Primus HSM family, Securosys Clouds HSM | Primus BYOK tool and documentation |
| StorMagic | ISV (Enterprise Key Management System) | Multiple HSM brands and models including
|
SvKMS and Azure Key Vault BYOK |
| Thales | Manufacturer |
|
Luna BYOK tool and documentation |
| Utimaco | Manufacturer, HSM as a service |
u.trust Anchor, CryptoServer | Utimaco BYOK tool and Integration guide |
Supported key types
| Key name | Key type | Key size/curve | Origin | Description |
|---|---|---|---|---|
| Key Exchange Key (KEK) | RSA-HSM | 2,048-bit 3,072-bit 4,096-bit |
Managed HSM | An HSM-backed RSA key pair generated in Managed HSM |
| Target key | ||||
| RSA-HSM | 2,048-bit 3,072-bit 4,096-bit |
Vendor HSM | The key to be transferred to the Managed HSM | |
| EC-HSM | P-256 P-384 P-521 |
Vendor HSM | The key to be transferred to the Managed HSM | |
| Symmetric key (oct-hsm) | 128-bit 192-bit 256-bit |
Vendor HSM | The key to be transferred to the Managed HSM | |
Generate and transfer your key to the Managed HSM
Step 1: Generate a KEK
A KEK is an RSA key that's generated in a Managed HSM. The KEK is used to encrypt the key you want to import (the target key).
The KEK must be:
- An RSA-HSM key (2,048-bit; 3,072-bit; or 4,096-bit)
- Generated in the same managed HSM where you intend to import the target key
- Created with allowed key operations set to
import
Note
The KEK must have 'import' as the only allowed key operation. 'import' is mutually exclusive with all other key operations.
Use the az keyvault key create command to create a KEK that has key operations set to import. Record the key identifier (kid) that's returned from the following command. (You'll use the kid value in Step 3.)
az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --hsm-name ContosoKeyVaultHSM
Step 2: Download the KEK public key
Use az keyvault key download to download the KEK public key to a .pem file. The target key you import is encrypted by using the KEK public key.
az keyvault key download --name KEKforBYOK --hsm-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem
Transfer the KEKforBYOK.publickey.pem file to your offline computer. You'll need this file in the next step.
Step 3: Generate and prepare your key for transfer
Refer to your HSM vendor's documentation to download and install the BYOK tool. Follow instructions from your HSM vendor to generate a target key, and then create a key transfer package (a BYOK file). The BYOK tool will use the kid from Step 1 and the KEKforBYOK.publickey.pem file you downloaded in Step 2 to generate an encrypted target key in a BYOK file.
Transfer the BYOK file to your connected computer.
Note
Importing RSA 1,024-bit keys is not supported. Importing EC-HSM P256K keys is supported.
Known issue: Importing an RSA 4K target key from Luna HSMs is only supported with firmware 7.4.0 or newer.
Step 4: Transfer your key to Managed HSM
To complete the key import, transfer the key transfer package (a BYOK file) from your disconnected computer to the internet-connected computer. Use the az keyvault key import command to upload the BYOK file to the Managed HSM.
az keyvault key import --hsm-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok
If the upload is successful, Azure CLI displays the properties of the imported key.
Next steps
You can now use this HSM-protected key in your Managed HSM. For more information, see this price and feature comparison.