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:
Note
All the following commands show two usage methods for CLI. 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.
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.
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys.
Select Generate/Import from the Generate/Import/Restore Backup dropdown.
Choose the key type (RSA-HSM, EC-HSM, or oct-HSM), set the key size or curve, name, and permitted operations, then select Create.
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
Use the Add-AzKeyVaultKey cmdlet 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.
Add-AzKeyVaultKey -HsmName <hsm-name> -Name myrsakey -KeyType RSA-HSM -Size 3072 -KeyOps wrapKey,unwrapKey
Create an EC key
This example shows how to create an EC key with the P-256 curve for sign and verify operations.
Add-AzKeyVaultKey -HsmName <hsm-name> -Name myec256key -KeyType EC-HSM -CurveName P-256 -KeyOps sign,verify -Tag @{usage='signing'; appname='myapp'}
Create a 256-bit symmetric key
This example shows how to create a 256-bit symmetric key for encrypt and decrypt operations.
Add-AzKeyVaultKey -HsmName <hsm-name> -Name myaeskey -KeyType oct-HSM -Size 256 -KeyOps encrypt,decrypt -Tag @{usage='encryption'; appname='myapp'}
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys.
Select the key you want to view. The portal displays the key's attributes, versions, 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
Use the Get-AzKeyVaultKey cmdlet to view attributes, versions, and tags for a key.
Get-AzKeyVaultKey -HsmName <hsm-name> -Name myrsakey
List keys
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys. The portal lists all keys in the Managed HSM.
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/
Use the Get-AzKeyVaultKey cmdlet to list all keys in a Managed HSM.
Get-AzKeyVaultKey -HsmName <hsm-name>
Delete a key
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys.
Select the key you want to delete.
Select Delete, and then confirm.
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
Use the Remove-AzKeyVaultKey cmdlet to delete a key. Soft-delete is always on, so a deleted key remains recoverable until the retention period expires.
Remove-AzKeyVaultKey -HsmName <hsm-name> -Name myrsakey
List deleted keys
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys.
Select Manage deleted keys to view keys in the soft-deleted state.
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/
Use the Get-AzKeyVaultKey cmdlet with the -InRemovedState parameter to list deleted keys.
Get-AzKeyVaultKey -HsmName <hsm-name> -InRemovedState
Recover (undelete) a deleted key
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys, then select Manage deleted keys.
Select the deleted key you want to recover.
Select Recover.
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
Use the Undo-AzKeyVaultKeyRemoval cmdlet to recover a deleted key.
Undo-AzKeyVaultKeyRemoval -HsmName <hsm-name> -Name myrsakey
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.
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys, then select Manage deleted keys.
Select the deleted key you want to purge.
Select Purge, and then confirm.
Warning
This operation permanently deletes your key.
Use the az keyvault key purge command to purge (permanently delete) a key.
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
Use the Remove-AzKeyVaultKey cmdlet with the -InRemovedState parameter to purge a deleted key.
Remove-AzKeyVaultKey -HsmName <hsm-name> -Name myrsakey -InRemovedState
Warning
This operation permanently deletes your key.
Create a single key backup
Key backup isn't currently available in the Azure portal. Use the Azure CLI or Azure PowerShell.
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/keys/myrsakey --file myrsakey.backup
Use the Backup-AzKeyVaultKey cmdlet to create a key backup. The backup file is an encrypted blob cryptographically tied to the Security Domain of the source HSM.
Backup-AzKeyVaultKey -HsmName <hsm-name> -Name myrsakey -OutputFile myrsakey.backup
Restore a single key from backup
In the Azure portal, navigate to your Managed HSM resource.
In the left menu, under Settings, select Keys.
Select Generate/Import/Restore Backup and choose Restore key from backup.
Browse to and select the backup file, then select Restore.
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/keys/myrsakey --file myrsakey.backup
Use the Restore-AzKeyVaultKey cmdlet to restore a single key. The source HSM where you created the backup must share the same security domain as the target HSM.
Note
The restore operation fails if a key with the same name exists in active or deleted state.
Restore-AzKeyVaultKey -HsmName <hsm-name> -InputFile myrsakey.backup
Import a key from a file
Key import isn't currently available in the Azure portal. Use the Azure CLI or Azure PowerShell.
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 import --id https://<hsm-name>.managedhsm.azure.net/keys/<key-name> --pem-file mycert.key --password 'mypassword'
Use the Add-AzKeyVaultKey cmdlet with the -KeyFilePath parameter to import a key from a PEM file.
Add-AzKeyVaultKey -HsmName <hsm-name> -Name myrsakey -KeyFilePath ./mycert.key -KeyFilePassword (ConvertTo-SecureString -String 'mypassword' -AsPlainText -Force) -KeyType RSA-HSM
To import a key from your on-premises HSM to managed HSM, see Import HSM-protected keys to Managed HSM (BYOK).
Next steps