Merge pull request #224930 from msmbaldwin/freshness

Updates

Author: prmerger-automator[bot]

articles/key-vault/keys/about-keys.md

@@ -9,13 +9,13 @@ tags: azure-resource-manager
 ms.service: key-vault
 ms.subservice: keys
 ms.topic: overview
-ms.date: 02/17/2021
+ms.date: 01/24/2023
 ms.author: mbaldwin
 ---
 
 # About keys
 
-Azure Key Vault provides two types of resources to store and manage cryptographic keys. Vaults support software-protected and HSM-protected (Hardware Security Module) keys. Managed HSMs only support HSM-protected keys. 
+Azure Key Vault provides two types of resources to store and manage cryptographic keys. Vaults support software-protected and HSM-protected (Hardware Security Module) keys. Managed HSMs only support HSM-protected keys.
 
 |Resource type|Key protection methods|Data-plane endpoint base URL|
 |--|--|--|

articles/key-vault/keys/byok-specification.md

@@ -3,13 +3,12 @@ title: Bring your own key specification - Azure Key Vault | Microsoft Docs
 description: This document described bring your own key specification. 
 services: key-vault
 author: mbaldwin
-manager: devtiw
 tags: azure-resource-manager
 
 ms.service: key-vault
 ms.subservice: keys
 ms.topic: conceptual
-ms.date: 02/04/2021
+ms.date: 01/24/2023
 ms.author: mbaldwin 
 ms.custom: devx-track-azurepowershell, devx-track-azurecli
 ---
@@ -20,7 +19,7 @@ This document describes specifications for importing HSM-protected keys from cus
 
 ## Scenario
 
-A Key Vault customer would like to securely transfer a key from their on-premises HSM outside Azure, into the HSM backing Azure Key Vault. The process of importing a key generated outside Key Vault is generally referred to as Bring Your Own Key (BYOK).
+A Key Vault customer would like to securely transfer a key from their on-premises HSM outside Azure, into the HSM backing Azure Key Vault. The process of importing a key generated outside Key Vault is referred to as Bring Your Own Key (BYOK).
 
 The following are the requirements:
 * The key to be transferred never exists outside an HSM in plain text form.
@@ -31,7 +30,7 @@ The following are the requirements:
 |Key Name|Key Type|Origin|Description|
 |---|---|---|---|
 |Key Exchange Key (KEK)|RSA|Azure Key Vault HSM|An HSM backed RSA key pair generated in Azure Key Vault
-Wrapping Key|AES|Vendor HSM|An [ephemeral] AES key generated by HSM on-prem
+Wrapping Key|AES|Vendor HSM|An [ephemeral] AES key generated by HSM on-premises
 Target Key|RSA, EC, AES (Managed HSM only)|Vendor HSM|The key to be transferred to the Azure Key Vault HSM
 
 **Key Exchange Key**: An HSM-backed key that customer generates in the key vault where the BYOK key will be imported. This KEK must have following properties:
@@ -51,20 +50,19 @@ To perform a key transfer, a user performs following steps:
 
 Customers use the BYOK tool and documentation provided by HSM vendor to complete Steps 3. It produces a Key Transfer Blob (a ".byok" file).
 
-
 ## HSM constraints
 
 Existing HSM may apply constraints on key that they manage, including:
 * The HSM may need to be configured to allow key wrap-based export
 * The target key may need to be marked CKA_EXTRACTABLE for the HSM to allow controlled export
-* In some cases, the KEK and wrapping key may need to be marked as CKA_TRUSTED. This allows it to be used to wrap keys in the HSM.
+* In some cases, the KEK and wrapping key may need to be marked as CKA_TRUSTED, which allows it to be used to wrap keys in the HSM.
 
 The configuration of source HSM is, generally, outside the scope of this specification. Microsoft expects the HSM vendor to produce documentation accompanying their BYOK tool to include any such configuration steps.
 
 > [!NOTE]
-> Steps 1, 2, and 4 described below can be performed using other interfaces such as Azure PowerShell and Azure Portal. They can also be performed programmatically using equivalent functions in Key Vault SDK.
+> Several of these steps can be performed using other interfaces such as Azure PowerShell and Azure Portal. They can also be performed programmatically using equivalent functions in Key Vault SDK.
 
-### Step 1: Generate KEK
+### Generate KEK
 
 Use the **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.
 
@@ -75,15 +73,15 @@ az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import
 > [!NOTE]
 > Services support different KEK lengths; Azure SQL, for instance, only supports key lengths of [2048 or 3072 bytes](/azure/azure-sql/database/transparent-data-encryption-byok-overview#requirements-for-configuring-customer-managed-tde). Consult the documentation for your service for specifics.
 
-### Step 2: Retrieve the public key of the KEK
+### Retrieve the public key of the KEK
 
 Download the public key portion of the KEK and store it into a PEM file.
 
 ```azurecli
 az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem
 ```
 
-### Steps 3: Generate key transfer blob using HSM vendor provided BYOK tool
+### Generate key transfer blob using HSM vendor provided BYOK tool
 
 Customer will use HSM Vendor provided BYOK tool to create a key transfer blob (stored as a ".byok" file). KEK public key (as a .pem file) will be one of the inputs to this tool.
 
@@ -121,16 +119,16 @@ If CKM_RSA_AES_KEY_WRAP_PAD is used, the JSON serialization of the transfer blob
 
 * kid = key identifier of KEK. For Key Vault keys it looks like this: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
 * alg = algorithm. 
-* dir = Direct mode, i.e. the referenced kid is used to directly protect the ciphertext which is an accurate representation of CKM_RSA_AES_KEY_WRAP
+* dir = Direct mode, that is, the referenced kid is used to directly protect the ciphertext that is an accurate representation of CKM_RSA_AES_KEY_WRAP
 * generator = an informational field that denotes the name and version of BYOK tool and the source HSM manufacturer and model. This information is intended for use in troubleshooting and support.
 
 The JSON blob is stored in a file with a ".byok" extension so that the Azure PowerShell/CLI clients treats it correctly when ‘Add-AzKeyVaultKey’ (PSH) or ‘az keyvault key import’ (CLI) commands are used.
 
-### Step 4: Upload key transfer blob to import HSM-key
+### Upload key transfer blob to import HSM-key
 
 Customer will transfer the Key Transfer Blob (".byok" file) to an online workstation and then run a **az keyvault key import** command to import this blob as a new HSM-backed key into Key Vault. 
 
-To import an RSA key use this command:
+To import an RSA key, use this command:
 ```azurecli
 az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok --ops encrypt decrypt
 ```

articles/key-vault/keys/hsm-protected-keys-byok.md

@@ -21,9 +21,9 @@ For added assurance when you use Azure Key Vault, you can import or generate a k
 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.
 
 > [!NOTE]
-> This functionality is not available for Azure China 21Vianet. 
-> 
-> This import method is available only for [supported HSMs](#supported-hsms). 
+> This functionality is not available for Azure China 21Vianet.
+>
+> This import method is available only for [supported HSMs](#supported-hsms).
 
 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?](../general/overview.md).
 
@@ -34,7 +34,7 @@ Here's an overview of the process. Specific steps to complete are described late
 * 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 and Managed HSM support RSA-HSM keys.
 * Download the KEK public key as a .pem file.
 * Transfer the KEK public key to an offline computer that is connected to an on-premises HSM.
-* In the offline computer, use the BYOK tool provided by your HSM vendor to create a BYOK file. 
+* In the offline computer, use the BYOK tool provided by your HSM vendor to create a BYOK file.
 * 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.
 * 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.
 * The KEK must be in the same key vault where the target key will be imported.
@@ -82,12 +82,12 @@ The following table lists prerequisites for using BYOK in Azure Key Vault:
 
 To generate and transfer your key to a Key Vault Premium or Managed HSM:
 
-* [Step 1: Generate a KEK](#step-1-generate-a-kek)
-* [Step 2: Download the KEK public key](#step-2-download-the-kek-public-key)
-* [Step 3: Generate and prepare your key for transfer](#step-3-generate-and-prepare-your-key-for-transfer)
-* [Step 4: Transfer your key to Azure Key Vault](#step-4-transfer-your-key-to-azure-key-vault)
+* [Step 1: Generate a KEK](#generate-a-kek)
+* [Step 2: Download the KEK public key](#download-the-kek-public-key)
+* [Step 3: Generate and prepare your key for transfer](#generate-and-prepare-your-key-for-transfer)
+* [Step 4: Transfer your key to Azure Key Vault](#transfer-your-key-to-azure-key-vault)
 
-### Step 1: Generate a KEK
+### Generate a KEK
 
 A KEK is an RSA key that's generated in a Key Vault Premium or Managed HSM. The KEK is used to encrypt the key you want to import (the *target* key).
 
@@ -99,7 +99,7 @@ The KEK must be:
 > [!NOTE]
 > 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 will use the `kid` value in [Step 3](#step-3-generate-and-prepare-your-key-for-transfer).)
+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 will use the `kid` value in [Step 3](#generate-and-prepare-your-key-for-transfer).)
 
 ```azurecli
 az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --vault-name ContosoKeyVaultHSM
@@ -110,7 +110,7 @@ or for Managed HSM
 az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --hsm-name ContosoKeyVaultHSM
 ```
 
-### Step 2: Download the KEK public key
+### Download the KEK public key
 
 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.
 
@@ -126,9 +126,9 @@ az keyvault key download --name KEKforBYOK --hsm-name ContosoKeyVaultHSM --file
 
 Transfer the KEKforBYOK.publickey.pem file to your offline computer. You will need this file in the next step.
 
-### Step 3: Generate and prepare your key for transfer
+### 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.
+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](#generate-a-kek) and the KEKforBYOK.publickey.pem file you downloaded in [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.
 
@@ -137,14 +137,16 @@ Transfer the BYOK file to your connected computer.
 > 
 > **Known issue**: Importing an RSA 4K target key from Luna HSMs is only supported with firmware 7.4.0 or newer.
 
-### Step 4: Transfer your key to Azure Key Vault
+### Transfer your key to Azure Key Vault
 
 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 Key Vault HSM.
 
 To import an RSA key use following command. Parameter --kty is optional and defaults to 'RSA-HSM'.
+
 ```azurecli
 az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok
 ```
+
 or for Managed HSM
 
 ```azurecli