Updates

Author: msmbaldwin

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
 ```