Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Note
Key Vault supports two types of resources: vaults and managed HSMs. This article is about Managed HSM. If you want to learn how to manage a vault, see Quickstart: Create a key vault using the Azure CLI.
For an overview of Managed HSM, see What is Managed HSM?
Prerequisites
An Azure subscription is required. If you don't have one, create a free account before you begin.
You also need:
- Azure CLI version 2.25.0 or later. Run
az --versionto find the version. If you need to install or upgrade, see Install the Azure CLI. - A managed HSM in your subscription. See Quickstart: Provision and activate a managed HSM using Azure CLI.
- To access keys using Azure SDKs, see .NET | Python | JavaScript
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.
Sign in to Azure
To sign in to Azure by using the CLI, enter:
az login
For more information about authentication options through the CLI, see Sign in with Azure CLI.
Note
All the following commands show two usage methods. One method uses the --hsm-name and --name (for key name) parameters. The other method uses the --id parameter, where you can specify the entire URL including the key name when appropriate. The latter method is useful when the caller (a user or an application) has no read access on the control plane and only restricted access on the data plane.
Note
Some interactions with key material require specific Managed HSM local RBAC permissions. For a full list of built-in Managed HSM local RBAC roles and permissions, see Managed HSM local RBAC built-in roles. To assign these permissions to a user, see Secure access to your managed HSMs.
Create an HSM key
Note
You can't export a key that's generated or imported into Managed HSM. The only exception to the no-export rule is when you create a key with a specific key release policy. This policy allows the key to be exported only to trusted confidential computing environments (secure enclaves) that you explicitly define. This limited export capability is designed for specific secure computing scenarios and isn't the same as a general-purpose key export. For recommended best practices for key portability and durability, see the linked article.
Use the az keyvault key create command to create a key.
Create an RSA key
This example shows how to create a 3072-bit RSA key that is only used for wrapKey and unwrapKey operations (--ops).
az keyvault key create --hsm-name <hsm-name> --name myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072
## OR
# Note the key name (myrsakey) in the URI
az keyvault key create --id https://<hsm-name>.managedhsm.azure.net/keys/myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072
The get operation only returns the public key and key attributes. It doesn't return the private key (if an asymmetric key) or the key material (if a symmetric key).
Create an EC key
The following example shows how to create an EC key with the P-256 curve. The key is only for sign and verify operations (--ops) and has two tags, usage and appname. Use tags to add extra metadata to the key for tracking and managing.
az keyvault key create --hsm-name <hsm-name> --name myec256key --ops sign verify --tags 'usage=signing' 'appname=myapp' --kty EC-HSM --curve P-256
## OR
# Note the key name (myec256key) in the URI
az keyvault key create --id https://<hsm-name>.managedhsm.azure.net/keys/myec256key --ops sign verify --tags 'usage=signing' 'appname=myapp' --kty EC-HSM --curve P-256
Create a 256-bit symmetric key
This example shows how to create a 256-bit symmetric key that's only for encrypt and decrypt operations (--ops).
az keyvault key create --hsm-name <hsm-name> --name myaeskey --ops encrypt decrypt --tags 'usage=encryption' 'appname=myapp' --kty oct-HSM --size 256
## OR
# Note the key name (myaeskey) in the URI
az keyvault key create --id https://<hsm-name>.managedhsm.azure.net/keys/myaeskey --ops encrypt decrypt --tags 'usage=encryption' 'appname=myapp' --kty oct-HSM --size 256
View key attributes and tags
Use the az keyvault key show command to view attributes, versions, and tags for a key.
az keyvault key show --hsm-name <hsm-name> --name myrsakey
## OR
# Note the key name (myaeskey) in the URI
az keyvault key show --id https://<hsm-name>.managedhsm.azure.net/keys/myrsakey
List keys
Use the az keyvault key list command to list all keys inside a managed HSM.
az keyvault key list --hsm-name <hsm-name>
## OR
# use full URI
az keyvault key list --id https://<hsm-name>.managedhsm.azure.net/
Delete a key
Use the az keyvault key delete command to delete a key from a managed HSM. Soft-delete is always on. Therefore, a deleted key stays in the deleted state and you can recover it until the number of retention days pass. After that, the key is purged (permanently deleted) with no recovery possible.
az keyvault key delete --hsm-name <hsm-name> --name myrsakey
## OR
# Note the key name (myaeskey) in the URI
az keyvault key delete --id https://<hsm-name>.managedhsm.azure.net/keys/myrsakey
List deleted keys
Use the az keyvault key list-deleted command to list all the keys in the deleted state in your managed HSM.
az keyvault key list-deleted --hsm-name <hsm-name>
## OR
# use full URI
az keyvault key list-deleted --id https://<hsm-name>.managedhsm.azure.net/
Recover (undelete) a deleted key
Use the az keyvault key list-deleted command to list all the keys in deleted state in your managed HSM. To recover (undelete) a key, use the --id parameter. You must note the recoveryId value of the deleted key obtained from the az keyvault key list-deleted command.
az keyvault key recover --hsm-name <hsm-name> --name myrsakey
## OR
# Note the key name (myaeskey) in the URI
az keyvault key recover --id https://<hsm-name>.managedhsm.azure.net/deletedKeys/myrsakey
Purge (permanently delete) a key
Use the az keyvault key purge command to purge (permanently delete) a key.
Note
If the managed HSM has purge protection enabled, the purge operation isn't permitted. The key is automatically purged when the retention period passes.
az keyvault key purge --hsm-name <hsm-name> --name myrsakey
## OR
# Note the key name (myaeskey) in the URI
az keyvault key purge --id https://<hsm-name>.managedhsm.azure.net/deletedKeys/myrsakey
Create a single key backup
Use az keyvault key backup to create a key backup. The backup file is an encrypted blob cryptographically tied to the Security Domain of the source HSM. You can only restore it in HSMs that share the same security domain. Read more about Security Domain.
az keyvault key backup --hsm-name <hsm-name> --name myrsakey --file myrsakey.backup
## OR
# Note the key name (myaeskey) in the URI
az keyvault key backup --id https://<hsm-name>.managedhsm.azure.net/deletedKeys/myrsakey --file myrsakey.backup
Restore a single key from backup
Use az keyvault key restore to restore a single key. The source HSM where you created the backup must share the same security domain as the target HSM where you're restoring the key.
Note
The restore operation fails if a key with the same name exists in active or deleted state.
az keyvault key restore --hsm-name <hsm-name> --name myrsakey --file myrsakey.backup
## OR
# Note the key name (myaeskey) in the URI
az keyvault key restore --id https://<hsm-name>.managedhsm.azure.net/deletedKeys/myrsakey --file myrsakey.backup
Import a key from a file
Use the az keyvault key import command to import a key (only RSA and EC) from a file. The certificate file must have a private key and must use PEM encoding (as defined in RFCs 1421, 1422, 1423, 1424).
az keyvault key import --hsm-name <hsm-name> --name myrsakey --pem-file mycert.key --pem-password 'mypassword'
## OR
# Note the key name (<key-name>) in the URI
az keyvault key recover --id https://<hsm-name>.managedhsm.azure.net/deletedKeys/<key-name> --pem-file mycert.key --password 'mypassword'
To import a key from your on-premises HSM to managed HSM, see Import HSM-protected keys to Managed HSM (BYOK).
Next steps
- For the complete Azure CLI reference for key vault commands, see Key Vault CLI reference.
- For programming references, see the Azure Key Vault developer's guide.
- To access keys using Azure SDKs, see: .NET, Python, JavaScript.
- To learn more about Managed HSM role management, see Managed HSM role management.
- To learn more about securing your Azure Managed HSM deployment, see Secure your Azure Managed HSM deployment.