edit pass: how-to-setup-cmk

Author: shawnmariejones

articles/cosmos-db/how-to-setup-cmk.md

@@ -12,22 +12,22 @@ ROBOTS: noindex, nofollow
 # Configure customer-managed keys for your Azure Cosmos account with Azure Key Vault
 
 > [!NOTE]
-> You'll need to request access to use this capability. Contact [[email protected]](mailto:[email protected]).
+> At this time, you must request access to use this capability. To do so, please contact [[email protected]](mailto:[email protected]).
 
 Data stored in your Azure Cosmos account is automatically and seamlessly encrypted. Azure Cosmos DB offers two options to manage the keys used to encrypt the data at rest:
 
-- **Service-managed keys**: By default, Microsoft manages the keys used to encrypt the data in your Azure Cosmos account.
+- **Service-managed keys**: By default, Microsoft manages the keys that are used to encrypt the data in your Azure Cosmos account.
 
-- **Customer-managed keys (CMK)**: You can choose to add a second layer of encryption with your own keys.
+- **Customer-managed keys (CMK)**: You can optionally choose to add a second layer of encryption with your own keys.
 
-You'll need to store your customer-managed keys in the [Azure Key Vault](../key-vault/key-vault-overview.md) and provide a key for each Azure Cosmos account that is enabled with customer-managed keys. This key is used to encrypt all the data stored in that account.
+You must store customer-managed keys in the [Azure Key Vault](../key-vault/key-vault-overview.md) and provide a key for each Azure Cosmos account that is enabled with customer-managed keys. This key is used to encrypt all the data stored in that account.
 
 > [!NOTE]
-> Customer-managed keys are only available for new Azure Cosmos accounts. You should configure them during account creation.
+> Currently, customer-managed keys are available only for new Azure Cosmos accounts. You should configure them during account creation.
 
 ## <a id="register-resource-provider"></a> Register the Azure Cosmos DB resource provider for your Azure subscription
 
-1. Sign into the [Azure portal](https://portal.azure.com/), go to your Azure subscription, and select **Resource providers** under the **Settings** tab:
+1. Sign in to the [Azure portal](https://portal.azure.com/), go to your Azure subscription, and select **Resource providers** under the **Settings** tab:
 
    !["Resource providers" entry from the left menu](./media/how-to-setup-cmk/portal-rp.png)
 
@@ -37,44 +37,44 @@ You'll need to store your customer-managed keys in the [Azure Key Vault](../key-
 
 ## Configure your Azure Key Vault instance
 
-To use customer-managed keys with Azure Cosmos DB, you'll need to set two properties on the Azure Key Vault instance that you plan to use to host your encryption keys. These properties include **soft-delete** and **do not purge**. These properties aren't enabled by default, but you can enable them by using either PowerShell or Azure CLI.
+Using customer-managed keys with Azure Cosmos DB requires you to set two properties on the Azure Key Vault instance that you plan to use to host your encryption keys. These properties include **Soft Delete** and **Do Not Purge**. These properties aren't enabled by default. You can enable them by using either PowerShell or the Azure CLI.
 
-To learn how to enable these properties on an existing Azure Key Vault instance, see the **Enabling soft-delete** and **Enabling purge protection** sections in either of these articles:
+To learn how to enable these properties on an existing Azure Key Vault instance, see the "Enabling soft-delete" and "Enabling Purge Protection" sections in one of the following articles:
 
 - [How to use soft-delete with PowerShell](../key-vault/key-vault-soft-delete-powershell.md)
 - [How to use soft-delete with Azure CLI](../key-vault/key-vault-soft-delete-cli.md)
 
 ## Add an access policy to your Azure Key Vault instance
 
-1. From the Azure portal, go to the Azure Key Vault instance that you plan to use to host your encryption keys. Select **Access policies** from the left menu:
+1. From the Azure portal, go to the Azure Key Vault instance that you plan to use to host your encryption keys. Select **Access Policies** from the left menu:
 
    !["Access policies" from the left menu](./media/how-to-setup-cmk/portal-akv-ap.png)
 
-1. Select **+ Add access policy**.
+1. Select **+ Add Access Policy**.
 
-1. Under the **Key permissions** dropdown menu, select **Get**, **Unwrap Key**, and **Wrap Key** permissions:
+1. Under the **Key permissions** drop-down menu, select **Get**, **Unwrap Key**, and **Wrap Key** permissions:
 
    ![Selecting the right permissions](./media/how-to-setup-cmk/portal-akv-add-ap-perm2.png)
 
-1. Under **Select principal**, select **None selected**. Then, search for **Azure Cosmos DB** principal and select it. Finally, select **Select** at the bottom. If the **Azure Cosmos DB** principal isn't in the list, you may need to reregister the **Microsoft.DocumentDB** resource provider, described in the [register the resource provider](#register-resource-provider) section of this article.
+1. Under **Select principal**, select **None selected**. Then, search for **Azure Cosmos DB** principal and select it. Finally, choose **Select** at the bottom. If the **Azure Cosmos DB** principal isn't in the list, you might need to re-register the **Microsoft.DocumentDB** resource provider as described in the [Register the resource provider](#register-resource-provider) section of this article.
 
    ![Select the Azure Cosmos DB principal](./media/how-to-setup-cmk/portal-akv-add-ap.png)
 
 1. Select **Add** to add the new access policy.
 
 ## Generate a key in Azure Key Vault
 
-1. From the Azure portal, go the Azure Key Vault instance that you plan to use to host your encryption keys, and select **Keys** from the left menu:
+1. From the Azure portal, go the Azure Key Vault instance that you plan to use to host your encryption keys. Then, select **Keys** from the left menu:
 
    !["Keys" entry from the left menu](./media/how-to-setup-cmk/portal-akv-keys.png)
 
-1. Select **Generate/Import**, provide a name for the new key, select an RSA key size (a minimum of 3072 is recommended for best security), and then select **Create**:
+1. Select **Generate/Import**, provide a name for the new key, and select an RSA key size. A minimum of 3072 is recommended for best security. Then select **Create**:
 
    ![Create a new key](./media/how-to-setup-cmk/portal-akv-gen.png)
 
-1. After the key is created, select the newly created key, and select its current version.
+1. After the key is created, select the newly created key, then its current version.
 
-1. Copy the key’s **Key Identifier**, except the part after the last forward slash:
+1. Copy the key's **Key Identifier**, except the part after the last forward slash:
 
    ![Copying the key's key identifier](./media/how-to-setup-cmk/portal-akv-keyid.png)
 
@@ -95,7 +95,7 @@ When you create a new Azure Cosmos DB account with PowerShell:
 - Use **2019-12-12** as the API version.
 
 > [!IMPORTANT]
-> You'll need to set the `Location` parameter explicitly for the account to be successfully created with customer-managed keys.
+> You must set the `Location` parameter explicitly for the account to be successfully created with customer-managed keys.
 
 ```powershell
 $resourceGroupName = "myResourceGroup"
@@ -119,14 +119,14 @@ New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
 
 ### Using an Azure Resource Manager template
 
-When you create a new Azure Cosmos account through an Azure Resource Manager template:
+When creating a new Azure Cosmos account through an Azure Resource Manager template:
 
 - Pass the URI of the Azure Key Vault key that you copied earlier under the **keyVaultKeyUri** property in the **properties** object.
 
 - Use **2019-12-12** as the API version.
 
 > [!IMPORTANT]
-> You'll need to set the `Location` parameter explicitly for the account to be successfully created with customer-managed keys.
+> You must set the `Location` parameter explicitly for the account to be successfully created with customer-managed keys.
 
 ```json
 {
@@ -168,7 +168,7 @@ When you create a new Azure Cosmos account through an Azure Resource Manager tem
 
 ```
 
-Deploy the template with this PowerShell script:
+Deploy the template with the following PowerShell script:
 
 ```powershell
 $resourceGroupName = "myResourceGroup"
@@ -186,7 +186,7 @@ New-AzResourceGroupDeployment `
 
 ## Frequently asked questions
 
-### Is there any additional charge when using customer-managed keys?
+### Is there any additional charge for using customer-managed keys?
 
 Yes. To account for the additional compute load that is required to manage data encryption and decryption with customer-managed keys, all operations executed against the Azure Cosmos account consume a 25 percent increase in [Request Units](./request-units.md).
 
@@ -200,19 +200,19 @@ All the data stored in your Azure Cosmos account is encrypted with the customer-
 
 - The property paths declared in your [indexing policies](./index-policy.md)
 
-- The values of your container's [partition key](./partitioning-overview.md)
+- The values of your containers' [partition keys](./partitioning-overview.md)
 
 ### Are customer-managed keys supported for existing Azure Cosmos accounts?
 
-This feature is currently available for new accounts only.
+This feature is currently available only for new accounts.
 
 ### Is there a plan to support finer granularity than account-level keys?
 
 Not currently, but container-level keys are being considered.
 
 ### How do customer-managed keys affect a backup?
 
-Azure Cosmos DB takes [regular and automatic backups](./online-backup-and-restore.md) of the data stored in your account. This operation backs up the encrypted data. To use the restored backup, the encryption key that you used at the time of the backup is required. This means that no revocation will have been made and the version of the key that was used at the time of the backup will still be enabled.
+Azure Cosmos DB takes [regular and automatic backups](./online-backup-and-restore.md) of the data stored in your account. This operation backs up the encrypted data. To use the restored backup, the encryption key that you used at the time of the backup is required. This means that no revocation was made and the version of the key that was used at the time of the backup will still be enabled.
 
 ### How do I revoke an encryption key?
 
@@ -230,5 +230,5 @@ The only operation possible when the encryption key has been revoked is account
 
 ## Next steps
 
-- Learn more about [data encryption in Azure Cosmos DB](./database-encryption-at-rest.md)
-- Get an overview of [secure access to data in Cosmos DB](secure-access-to-data.md)
+- Learn more about [data encryption in Azure Cosmos DB](./database-encryption-at-rest.md).
+- Get an overview of [secure access to data in Cosmos DB](secure-access-to-data.md).