Merge pull request #2614 from msmbaldwin/mhsm-quickstarts-includes

Add Managed HSM SDK quickstarts and refactor includes

Author: meganbradley

articles/key-vault/includes/azure-subscription-prerequisite.md

@@ -0,0 +1,10 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.topic: include
+ms.date: 03/24/2026
+# Include: Azure subscription prerequisite sentence
+---
+
+You need an Azure subscription. If you don't have one, create a [free account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).

articles/key-vault/includes/managed-hsm/azure-subscription-prerequisite.md

@@ -0,0 +1,10 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.topic: include
+ms.date: 03/24/2026
+# Include: Azure subscription prerequisite sentence
+---
+
+You need an Azure subscription. If you don't have one, create a [free account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).

articles/key-vault/includes/managed-hsm/billing-warning.md

@@ -0,0 +1,12 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/13/2026
+# Include: Managed HSM billing warning
+---
+
+> [!WARNING]
+> Managed HSM instances are always in use. If you enable purge protection by using the `--enable-purge-protection` flag, you pay for the entire retention period.

articles/key-vault/includes/managed-hsm/sdk-next-steps.md

@@ -0,0 +1,14 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/24/2026
+# Include: SDK quickstart next steps
+---
+
+- Learn about [Secure access to your managed HSMs](/azure/key-vault/managed-hsm/how-to-secure-access)
+- Configure [automated key rotation](/azure/key-vault/managed-hsm/key-rotation)
+- Review [Managed HSM best practices](/azure/key-vault/managed-hsm/secure-managed-hsm)
+- Learn about [Managed HSM local RBAC built-in roles](/azure/key-vault/managed-hsm/built-in-roles)

…ault/includes/managed-hsm/sdk-prereqs.md …ncludes/managed-hsm/sdk-prerequisites.mdarticles/key-vault/includes/managed-hsm/sdk-prereqs.md renamed to articles/key-vault/includes/managed-hsm/sdk-prerequisites.md articles/key-vault/includes/managed-hsm/sdk-prereqs.md renamed to articles/key-vault/includes/managed-hsm/sdk-prerequisites.md

@@ -39,19 +39,19 @@ Here's how to configure Managed HSM firewalls by using the Azure CLI:
 1. Use the [az keyvault update-hsm](/cli/azure/keyvault#az-keyvault-update-hsm) command to set the default action to Deny before creating a firewall.
 
    ```azurecli
-   az keyvault update-hsm --resource-group "myresourcegroup" --hsm-name "mymanagedhsm" --default-action Deny
+   az keyvault update-hsm --resource-group "ContosoResourceGroup" --hsm-name "ContosoMHSM" --default-action Deny
    ```
 
 1. Use the [az keyvault network-rule add](/cli/azure/keyvault/network-rule#az-keyvault-network-rule-add) command to add an IP address range to allow traffic.
 
    ```azurecli
-   az keyvault network-rule add --resource-group "myresourcegroup" --hsm-name "mymanagedhsm" --ip-address "191.10.18.0/24"
+   az keyvault network-rule add --resource-group "ContosoResourceGroup" --hsm-name "ContosoMHSM" --ip-address "191.10.18.0/24"
    ```
 
-1. If this key vault should be accessible by any trusted services, use the [az keyvault update](/cli/azure/keyvault#az-keyvault-update) command to set bypass to AzureServices.
+1. If any trusted services need access to this key vault, use the [az keyvault update](/cli/azure/keyvault#az-keyvault-update) command to set bypass to AzureServices.
 
    ```azurecli
-   az keyvault update --resource-group "myresourcegroup" --hsm-name "mymanagedhsm" --bypass AzureServices
+   az keyvault update --resource-group "ContosoResourceGroup" --hsm-name "ContosoMHSM" --bypass AzureServices
    ```
 
 # [Azure PowerShell](#tab/azure-powershell)
@@ -62,15 +62,15 @@ Here's how to configure Managed HSM firewalls by using PowerShell:
 1. Use the [Update-AzKeyVaultManagedHsmNetworkRuleSet](/powershell/module/az.keyvault/update-azkeyvaultmanagedhsmnetworkruleset) cmdlet to set default action to Deny and add an IP address range to allow traffic.
 
    ```powershell
-   Update-AzKeyVaultManagedHsmNetworkRuleSet -Name "mymanagedhsm" -ResourceGroupName "myresourcegroup" -DefaultAction Deny -IpAddressRange @('16.17.18.0/24') -PassThru 
+   Update-AzKeyVaultManagedHsmNetworkRuleSet -Name "ContosoMHSM" -ResourceGroupName "ContosoResourceGroup" -DefaultAction Deny -IpAddressRange @('16.17.18.0/24') -PassThru 
    ```
 
    Include `-ReplaceAllRules` to overwrite IP Lists. Otherwise, the command merges the newly included rules.
 
-1. If this managed HSM should be accessible by any trusted services, use the [Update-AzKeyVaultManagedHsmNetworkRuleSet](/powershell/module/az.keyvault/update-azkeyvaultmanagedhsmnetworkruleset) cmdlet to set bypass to AzureServices.
+1. If any trusted services need access to this managed HSM, use the [Update-AzKeyVaultManagedHsmNetworkRuleSet](/powershell/module/az.keyvault/update-azkeyvaultmanagedhsmnetworkruleset) cmdlet to set bypass to AzureServices.
 
    ```powershell
-   Update-AzKeyVaultManagedHsmNetworkRuleSet -Name "mymanagedhsm" -Bypass AzureServices
+   Update-AzKeyVaultManagedHsmNetworkRuleSet -Name "ContosoMHSM" -Bypass AzureServices
    ```
 
 ---

…s/managed-hsm/security-domain-prereqs.md …ged-hsm/security-domain-prerequisites.mdarticles/key-vault/includes/managed-hsm/security-domain-prereqs.md renamed to articles/key-vault/includes/managed-hsm/security-domain-prerequisites.md articles/key-vault/includes/managed-hsm/security-domain-prereqs.md renamed to articles/key-vault/includes/managed-hsm/security-domain-prerequisites.md

@@ -21,7 +21,10 @@ This tutorial provides a practical implementation example of access control for
 
 ## Prerequisites
 
-* An Azure subscription. If you don't have one, you can sign up for a [free trial](https://azure.microsoft.com/pricing/free-trial).
+[!INCLUDE [Azure subscription prerequisite](../includes/azure-subscription-prerequisite.md)]
+
+You also need:
+
 * The Azure CLI version 2.25.0 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install the Azure CLI](/cli/azure/install-azure-cli).
 * A managed HSM in your subscription. See [Quickstart: Provision and activate a managed HSM using Azure CLI](quick-create-cli.md) to provision and activate a managed HSM.
 

articles/key-vault/managed-hsm/backup-restore.md

@@ -13,14 +13,14 @@ ms.author: mbaldwin
 
 # 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-3 Level 3 validated) to protect your keys.
+ Azure Key Vault Managed HSM supports importing keys generated in your on-premises hardware security module (HSM). The keys never leave the HSM protection boundary. This scenario is often referred to as *bring your own key (BYOK)*. Managed HSM uses the Marvell LiquidSecurity HSM adapters (FIPS 140-3 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 import method is available only for [supported HSMs](#supported-hsms). 
 
-For more information, and for a tutorial to get started using Managed HSM, see [What is Managed HSM?](overview.md).
+For more information, and for a tutorial to get started using Managed HSM, see [What is Managed HSM?](overview.md)
 
 ## Overview
 
@@ -33,26 +33,27 @@ Here's an overview of the process. Specific steps to complete are described late
 * 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.
+* When you upload the BYOK file 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:
+[!INCLUDE [Azure subscription prerequisite](../includes/azure-subscription-prerequisite.md)]
 
-* A subscription to Microsoft Azure. If you don't have one, you can sign up for a [free trial](https://azure.microsoft.com/pricing/free-trial).
-* The Azure CLI version 2.12.0 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install the Azure CLI]( /cli/azure/install-azure-cli).
-* A managed HSM the [supported HSMs list](#supported-hsms) in your subscription. See [Quickstart: Provision and activate a managed HSM using Azure CLI](quick-create-cli.md) to provision and activate a managed HSM.
+You also need:
+
+* Azure CLI version 2.12.0 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install the Azure CLI](/cli/azure/install-azure-cli).
+* A managed HSM in the [supported HSMs list](#supported-hsms) in your subscription. To provision and activate a managed HSM, see [Quickstart: Provision and activate a managed HSM using Azure CLI](quick-create-cli.md).
 
 [!INCLUDE [cloud-shell-try-it.md](~/reusable-content/ce-skilling/azure/includes/cloud-shell-try-it.md)]
 
-To sign in to Azure using the CLI, type:
+To sign in to Azure by using the CLI, type:
 
 ```azurecli
 az login
 ```
 
-For more information on login options via the CLI, take a look at [sign in with Azure CLI](/cli/azure/authenticate-azure-cli)
+For more information on authentication options through the CLI, see [sign in with Azure CLI](/cli/azure/authenticate-azure-cli).
 
 ## Supported HSMs
 
@@ -86,20 +87,20 @@ For more information on login options via the CLI, take a look at [sign in with
 
 ### 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).
+A KEK is an RSA key that you generate in a Managed HSM. Use the KEK 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
+- 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.
+> 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](/cli/azure/keyvault/key#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](#step-3-generate-and-prepare-your-key-for-transfer).)
 
 ```azurecli-interactive
-az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --hsm-name ContosoKeyVaultHSM
+az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --hsm-name ContosoMHSM
 ```
 ---
 
@@ -109,20 +110,20 @@ az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import
 Use [az keyvault key download](/cli/azure/keyvault/key#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.
 
 ```azurecli-interactive
-az keyvault key download --name KEKforBYOK --hsm-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem
+az keyvault key download --name KEKforBYOK --hsm-name ContosoMHSM --file KEKforBYOK.publickey.pem
 ```
 ---
 
-Transfer the KEKforBYOK.publickey.pem file to your offline computer. You'll need this file in the next step.
+Transfer the `KEKforBYOK.publickey.pem` file to your offline computer. You 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](#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.
+To download and install the BYOK tool, see your HSM vendor's documentation. Follow the instructions from your HSM vendor to generate a target key, and then create a key transfer package (a BYOK file). The BYOK tool uses 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.
 
 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.
+> Importing RSA 1,024-bit keys isn't 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.
 
@@ -131,7 +132,7 @@ Transfer the BYOK file to your connected computer.
 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#az-keyvault-key-import) command to upload the BYOK file to the Managed HSM.
 
 ```azurecli-interactive
-az keyvault key import --hsm-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok
+az keyvault key import --hsm-name ContosoMHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok
 ```
 
 If the upload is successful, Azure CLI displays the properties of the imported key.