You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: How to generate and transfer HSM-protected keys for Azure Key Vault - Azure Key Vault | Microsoft Docs
3
-
description: Use this article to help you plan for, generate, and then transfer your own HSM-protected keys to use with Azure Key Vault. Also known as BYOK or bring your own key.
3
+
description: Use this article to help you plan for, generate, and transfer your own HSM-protected keys to use with Azure Key Vault. Also known as bring your own key (BYOK).
4
4
services: key-vault
5
5
author: amitbapat
6
6
manager: devtiw
@@ -16,107 +16,117 @@ ms.author: ambapat
16
16
# Import HSM-protected keys to Key Vault (preview)
17
17
18
18
> [!NOTE]
19
-
> This feature is in preview and only available in **East US 2 EUAP** and **Central US EUAP** regions.
19
+
> This feature is in preview and available only in the Azure regions *East US 2 EUAP* and *Central US EUAP*.
20
20
21
-
For added assurance when using Azure Key Vault, you can import or generate keys in hardware security modules (HSMs) that never leave the HSM boundary. This scenario is often referred to as *bring your own key*, or BYOK. Azure Key Vault uses nCipher nShield family of HSMs (FIPS 140-2 Level 2 validated) to protect your keys.
21
+
For added assurance when you use Azure Key Vault, you can import or generate a key in a hardware security module (HSM); the key will never leave the HSM boundary. This scenario often is referred to as *bring your own key* (BYOK). Key Vault uses the nCipher nShield family of HSMs (FIPS 140-2 Level 2 validated) to protect your keys.
22
22
23
-
Use the information in this topic to help you plan for, generate, and then transfer your own HSM-protected keys to use with Azure Key Vault.
23
+
Use the information in this article to help you plan for, generate, and transfer your own HSM-protected keys to use with Azure Key Vault.
24
24
25
25
> [!NOTE]
26
26
> This functionality is not available for Azure China 21Vianet.
27
27
>
28
-
> This import method is only available for [supported HSMs](#supported-hsms).
28
+
> This import method is available only for [supported HSMs](#supported-hsms).
29
29
30
-
For more information about Azure Key Vault, see [What is Azure Key Vault?](key-vault-overview.md) For a getting started tutorial, which includes creating a key vault for HSM-protected keys, see [What is Azure Key Vault?](key-vault-overview.md).
30
+
For more information, and for a tutorial to get started using Key Vault (including how to create a key vault for HSM-protected keys), see [What is Azure Key Vault?](key-vault-overview.md).
31
31
32
32
## Overview
33
33
34
-
* Generate a key (referred to as Key Exchange Key or KEK) in key vault. This must be an RSA-HSM key with 'import' as the only key operation. Only key vault premium SKU supports RSA-HSM keys.
35
-
* Download the public key of KEK as a .pem file
36
-
* Transfer KEK public key to your offline workstation connected to on-premise HSM.
37
-
* From your offline workstation, use the BYOK tool provided by your HSM vendor to create a BYOK file.
38
-
* The target key is encrypted with a KEK, which stays encrypted until it is transferred to the Azure Key Vault HSMs. Only the encrypted version of your key leaves the on-premise HSM.
39
-
* The KEK that is generated inside the Azure Key Vault HSMs and is not exportable. The HSMs enforce that there can be no clear version of the KEK outside the Key Vault HSMs.
40
-
* The KEK must be in the same key vault where the target key is to be imported.
41
-
* When the BYOK file is uploaded to Key Vault, Key Vault HSMs use the KEK private key to decrypt the target key material and import it as an HSM key. This operation happens entirely inside Key Vault HSMs and the target key always remains in the HSM protection boundary.
34
+
Here's an overview of the process. Specific steps to complete are described later in the article.
35
+
36
+
* In Key Vault, generate a key (referred to as a *Key Exchange Key* (KEK)). The KEK must be an RSA-HSM key that has only the `import` key operation. Only Key Vault Premium SKU supports RSA-HSM keys.
37
+
* Download the KEK public key as a .pem file.
38
+
* Transfer the KEK public key to an offline computer that is connected to an on-premises HSM.
39
+
* In the offline computer, use the BYOK tool provided by your HSM vendor to create a BYOK file.
40
+
* The target key is encrypted with a KEK, which stays encrypted until it is transferred to the Key Vault HSM. Only the encrypted version of your key leaves the on-premises HSM.
41
+
* A KEK that's generated inside a Key Vault HSM is not exportable. HSMs enforce the rule that no clear version of a KEK exists outside a Key Vault HSM.
42
+
* The KEK must be in the same key vault where the target key will be imported.
43
+
* When the BYOK file is uploaded to Key Vault, a Key Vault HSM uses the KEK private key to decrypt the target key material and import it as an HSM key. This operation happens entirely inside a Key Vault HSM. The target key always remains in the HSM protection boundary.
42
44
43
45
## Prerequisites
44
46
45
-
See the following table for a list of prerequisites for bring your own key (BYOK) for Azure Key Vault.
47
+
The following table lists prerequisites for using BYOK in Azure Key Vault:
46
48
47
49
| Requirement | More information |
48
50
| --- | --- |
49
-
|A subscription to Azure |To create an Azure Key Vault, you need an Azure subscription:[Sign up for free trial](https://azure.microsoft.com/pricing/free-trial/)|
50
-
| A key vault (Premium SKU) to import HSM-protected keys |For more information about the service tiers and capabilities for Azure Key Vault, see the [Azure Key Vault Pricing](https://azure.microsoft.com/pricing/details/key-vault/) website. |
51
-
| An HSM from supported HSMs list along with BYOK tool and instructions provided by your HSM vendor | You must have access to a Hardware Security Module and basic operational knowledge of your HSMs. See [Supported HSMs](#supported-hsms). |
52
-
| Azure CLI version 2.1.0 or newer|Please see [Install the Azure CLI](/cli/azure/install-azure-cli?view=azure-cli-latest) for more information.|
51
+
|An Azure subscription |To create a key vault in Azure Key Vault, you need an Azure subscription.[Sign up for a free trial](https://azure.microsoft.com/pricing/free-trial/).|
52
+
| A Key Vault Premium SKU to import HSM-protected keys |For more information about the service tiers and capabilities in Azure Key Vault, see [Key Vault Pricing](https://azure.microsoft.com/pricing/details/key-vault/). |
53
+
| An HSM from the supported HSMs list and a BYOK tool and instructions provided by your HSM vendor | You must have permissions for an HSM and basic knowledge of how to use your HSM. See [Supported HSMs](#supported-hsms). |
54
+
| Azure CLI version 2.1.0 or later|See [Install the Azure CLI](/cli/azure/install-azure-cli?view=azure-cli-latest).|
|Thales|SafeNet Luna HSM 7 family with firmware version 7.3 or newer|[SafeNet Luna BYOK tool and documentation](https://supportportal.thalesgroup.com/csm?id=kb_article_view&sys_kb_id=3892db6ddb8fc45005c9143b0b961987&sysparm_article=KB0021016)|
59
-
60
+
|Thales|SafeNet Luna HSM 7 family with firmware version 7.3 or later|[SafeNet Luna BYOK tool and documentation](https://supportportal.thalesgroup.com/csm?id=kb_article_view&sys_kb_id=3892db6ddb8fc45005c9143b0b961987&sysparm_article=KB0021016)|
60
61
61
62
> [!NOTE]
62
-
> To import HSM-protected keys from nCipher nShield family of HSMs[Use legacy BYOK procedure](hsm-protected-keys-legacy.md)
63
+
> To import HSM-protected keys from the nCipher nShield family of HSMs, use the [legacy BYOK procedure](hsm-protected-keys-legacy.md).
63
64
65
+
## Supported key types
64
66
65
-
## Generate and transfer your key to Azure Key Vault HSM
|Target key|RSA|2,048-bit<br />3,072-bit<br />4,096-bit|Vendor HSM|The key to be transferred to the Azure Key Vault HSM|
66
71
67
-
You will use the following steps to generate and transfer your key to an Azure Key Vault HSM:
72
+
## Generate and transfer your key to the Key Vault HSM
73
+
74
+
To generate and transfer your key to a Key Vault HSM:
68
75
69
76
*[Step 1: Generate a KEK](#step-1-generate-a-kek)
70
-
*[Step 2: Download KEK public key](#step-2-download-kek-public-key)
77
+
*[Step 2: Download the KEK public key](#step-2-download-the-kek-public-key)
71
78
*[Step 3: Generate and prepare your key for transfer](#step-3-generate-and-prepare-your-key-for-transfer)
72
79
*[Step 4: Transfer your key to Azure Key Vault](#step-4-transfer-your-key-to-azure-key-vault)
73
80
74
81
### Step 1: Generate a KEK
75
82
76
-
The KEK (Key Exchange Key) is an RSA key generated in Key Vault's HSM. This key is used to encrypt the key to be imported (target key).
77
-
78
-
KEK must be:
79
-
1. an **RSA-HSM** key (2048-bit or 3072-bit or 4096-bit)
80
-
2. generated in the same key vault where you intend to import the target key
81
-
3. created with allowed key operations set to **import**
83
+
A KEK is an RSA key that's generated in a Key Vault HSM. The KEK is used to encrypt the key you want to import (the *target* key).
82
84
83
-
Use the [az keyvault key create](/cli/azure/keyvault/key?view=azure-cli-latest#az-keyvault-key-create) command to create KEK with key operations set to import. Note down the key identifier 'kid' returned from the below command. You'll need it in [Step 3](#step-3-generate-and-prepare-your-key-for-transfer).
85
+
The KEK must be:
86
+
- An RSA-HSM key (2,048-bit; 3,072-bit; or 4,096-bit)
87
+
- Generated in the same key vault where you intend to import the target key
88
+
- Created with allowed key operations set to `import`
84
89
90
+
Use the [az keyvault key create](/cli/azure/keyvault/key?view=azure-cli-latest#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 will use the `kid` value in [Step 3](#step-3-generate-and-prepare-your-key-for-transfer).)
Use the [az keyvault key download](/cli/azure/keyvault/key?view=azure-cli-latest#az-keyvault-key-download) to download the KEK public key into a .pem file. The target key you import is encrypted using the KEK public key.
98
+
Use [az keyvault key download](/cli/azure/keyvault/key?view=azure-cli-latest#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.
93
99
94
100
```azurecli
95
101
az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem
96
102
```
97
103
98
-
Transfer the KEKforBYOK.publickey.pem file to your offline workstation. You will need this file during next step.
104
+
Transfer the KEKforBYOK.publickey.pem file to your offline computer. You will need this file in the next step.
99
105
100
106
### Step 3: Generate and prepare your key for transfer
101
107
102
-
Please refer to your HSM vendor's documentation to download and install the BYOK tool. Follow instruction 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 key identifier from [Step 1](#step-1-generate-a-kek) and KEKforBYOK.publickey.pem file you downloaded in [Step 2](#step-2-download-kek-public-key) to generate an encrypted target key in a BYOK file.
108
+
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](#step-1-generate-a-kek) and the KEKforBYOK.publickey.pem file you downloaded in [Step 2](#step-2-download-the-kek-public-key) to generate an encrypted target key in a BYOK file.
103
109
104
-
Transfer the BYOK file to your connected workstation.
110
+
Transfer the BYOK file to your connected computer.
105
111
106
112
> [!NOTE]
107
-
> Target key must be an RSA key of size 2048-bit or 3072-bit or 4096-bit. Importing Elliptic Curve keys is not supported at this time.
108
-
> <br/><strong>Known issue:</strong> Importing RSA 4K target key from SafeNet Luna HSMs fails. When the issue is resolved this document will be updated.
113
+
> Importing RSA 1,024-bit keys is not supported. Currently, importing an Elliptic Curve (EC) key is not supported.
114
+
>
115
+
> **Known issue**: Importing an RSA 4K target key from SafeNet Luna HSMs fails. When the issue is resolved, this article will be updated.
109
116
110
117
### Step 4: Transfer your key to Azure Key Vault
111
118
112
-
For this final step, transfer the Key Transfer Package (a BYOK file) from your disconnected workstation to the Internet-connected workstation and then use the [az keyvault key import](/cli/azure/keyvault/key?view=azure-cli-latest#az-keyvault-key-import) command to upload the BYOK file the Azure Key Vault HSM, to complete the key import.
119
+
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](/cli/azure/keyvault/key?view=azure-cli-latest#az-keyvault-key-import) command to upload the BYOK file to the Key Vault HSM.
113
120
114
121
```azurecli
115
122
az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok
116
123
```
117
124
118
-
If the upload is successful, you see displayed the properties of the key that you just imported.
125
+
If the upload is successful, Azure CLI displays the properties of the imported key.
119
126
120
127
## Next steps
121
128
122
-
You can now use this HSM-protected key in your key vault. For more information, see this price and feature [comparison](https://azure.microsoft.com/pricing/details/key-vault/).
129
+
You can now use this HSM-protected key in your key vault. For more information, see [this price and feature comparison](https://azure.microsoft.com/pricing/details/key-vault/).
0 commit comments