Full backup and restore and selective key restore

Article
01/10/2024

Note

This feature is only available for resource type managed HSM.

Managed HSM supports creating a full backup of the entire contents of the HSM including all keys, versions, attributes, tags, and role assignments. The backup is encrypted with cryptographic keys associated with the HSM's security domain.

Backup is a data plane operation. The caller initiating the backup operation must have permission to perform dataAction Microsoft.KeyVault/managedHsm/backup/start/action.

Only following built-in roles have permission to perform full backup:

Managed HSM Administrator
Managed HSM Backup

There are two ways to execute a full backup/restore:

Assigning a User-Assigned Managed Identity (UAMI) to the Managed HSM service. You can back up and restore your MHSM using a user assigned managed identity regardless of whether your storage account has public network access or private network access enabled. If storage account is behind a private endpoint, the UAMI method works with trusted service bypass to allow for backup and restore.
Using storage container SAS token with permissions 'crdw'. Backing up and restoring using storage container SAS token requires your storage account to have public network access enabled.

You must provide the following information to execute a full backup:

HSM name or URL
Storage account name
Storage account blob storage container
User assigned managed identity OR storage container SAS token with permissions 'crdw'

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.

Prerequisites if backing up and restoring using user assigned managed identity:

Ensure you have the Azure CLI version 2.56.0 or later. Run az --version to find the version. If you need to install or upgrade, see Install the Azure CLI.
Create a user assigned managed identity.
Create a storage account (or use an existing storage account).
If public network access is disabled on your storage account, enable trusted service bypass on the storage account in the “Networking” tab, under “Exceptions.”
Provide ‘storage blob data contributor’ role access to the user assigned managed identity created in step #2 by going to the “Access Control” tab on the portal -> Add Role Assignment. Then select “managed identity” and select the managed identity created in step#2 -> Review + Assign

Create the Managed HSM and associate the managed identity with below command.

az keyvault create --hsm-name mhsmdemo2 –l mhsmlocation -- retention-days 7 --administrators "initialadmin" --mi-user-assigned "/subscriptions/subid/resourcegroups/mhsmrgname/providers/Microsoft.ManagedIdentity/userAssignedIdentities/userassignedidentitynamefromstep2"

If you have an existing Managed HSM, associate the managed identity by updating the MHSM with the below command.

 az keyvault update-hsm --hsm-name mhsmdemo2 --mi-user-assigned "/subscriptions/subid/resourcegroups/mhsmrgname/providers/Microsoft.ManagedIdentity/userAssignedIdentities/userassignedidentitynamefromstep2"

Full backup

Backup is a long running operation but immediately returns a Job ID. You can check the status of backup process using this Job ID. The backup process creates a folder inside the designated container with a following naming pattern mhsm-{HSM_NAME}-{YYYY}{MM}{DD}{HH}{mm}{SS}, where HSM_NAME is the name of managed HSM being backed up and YYYY, MM, DD, HH, MM, mm, SS are the year, month, date, hour, minutes, and seconds of date/time in UTC when the backup command was received.

While the backup is in progress, the HSM might not operate at full throughput as some HSM partitions will be busy performing the backup operation.

Backup HSM using user assigned managed identity

az keyvault backup start --use-managed-identity true --hsm-name mhsmdemo2 --storage-account-name mhsmdemobackup --blob-container-name mhsmdemobackupcontainer

Backup HSM using SAS token

# time for 500 minutes later for SAS token expiry

end=$(date -u -d "500 minutes" '+%Y-%m-%dT%H:%MZ')

# Get storage account key

skey=$(az storage account keys list --query '[0].value' -o tsv --account-name mhsmdemobackup --subscription {subscription-id})

# Create a container

az storage container create --account-name  mhsmdemobackup --name mhsmdemobackupcontainer  --account-key $skey

# Generate a container sas token

sas=$(az storage container generate-sas -n mhsmdemobackupcontainer --account-name mhsmdemobackup --permissions crdw --expiry $end --account-key $skey -o tsv --subscription {subscription-id})

# Backup HSM

az keyvault backup start --hsm-name mhsmdemo2 --storage-account-name mhsmdemobackup --blob-container-name mhsmdemobackupcontainer --storage-container-SAS-token $sas --subscription {subscription-id}

Full restore

Full restore allows you to completely restore the contents of the HSM with a previous backup, including all keys, versions, attributes, tags, and role assignments. Everything currently stored in the HSM will be wiped out, and it will return to the same state it was in when the source backup was created.

Important

Full restore is a very destructive and disruptive operation. Therefore it is mandatory to have completed a full backup at least 30 minutes prior to a restore operation can be performed.

Restore is a data plane operation. The caller starting the restore operation must have permission to perform dataAction Microsoft.KeyVault/managedHsm/restore/start/action. The source HSM where the backup was created and the destination HSM where the restore will be performed must have the same Security Domain. See more about Managed HSM Security Domain.

There are 2 ways to execute a full restore. You must provide the following information to execute a full restore:

HSM name or URL
Storage account name
Storage account blob container
User assigned managed identity OR storage container SAS token with permissions rl
Storage container folder name where the source backup is stored

Restore is a long running operation but will immediately return a Job ID. You can check the status of the restore process using this Job ID. When the restore process is in progress, the HSM enters a restore mode and all data plane command (except check restore status) are disabled.

Restore HSM using user assigned managed identity

az keyvault restore start --hsm-name mhsmdemo2 --storage-account-name mhsmdemobackup --blob-container-name mhsmdemobackupcontainer --backup-folder mhsm-backup-foldername --use-managed-identity true

Restore HSM using SAS token

# time for 500 minutes later for SAS token expiry

end=$(date -u -d "500 minutes" '+%Y-%m-%dT%H:%MZ')

# Get storage account key

skey=$(az storage account keys list --query '[0].value' -o tsv --account-name mhsmdemobackup --subscription {subscription-id})

# Generate a container sas token

sas=$(az storage container generate-sas -n mhsmdemobackupcontainer --account-name mhsmdemobackup --permissions rl --expiry $end --account-key $skey -o tsv --subscription {subscription-id})

# Restore HSM

az keyvault restore start --hsm-name mhsmdemo2 --storage-account-name mhsmdemobackup --blob-container-name mhsmdemobackupcontainer --storage-container-SAS-token $sas --backup-folder mhsm-mhsmdemo-2020083120161860

Selective key restore

Selective key restore allows you to restore one individual key with all its key versions from a previous backup to an HSM.

Selective key restore using user assigned managed identity

az keyvault restore start --hsm-name mhsmdemo2 --storage-account-name mhsmdemobackup --blob-container-name mhsmdemobackupcontainer --backup-folder mhsm-backup-foldername --use-managed-identity true --key-name rsa-key2

Selective key restore using SAS token

az keyvault restore start --hsm-name mhsmdemo2 --storage-account-name mhsmdemobackup --blob-container-name mhsmdemobackupcontainer --storage-container-SAS-token $sas --backup-folder mhsm-mhsmdemo-2020083120161860 -–key-name rsa-key2

Next Steps

See Manage a Managed HSM using the Azure CLI.
Learn more about Managed HSM Security Domain