Merge pull request #100103 from tamram/tamram-0102

PMEds28 · web-flow · commit ad335be07ae7 · 2020-01-05T08:41:13.000Z
add new sections for CMK configuration
diff --git a/articles/storage/common/storage-encryption-key-model-get.md b/articles/storage/common/storage-encryption-key-model-get.md
@@ -7,7 +7,7 @@ author: tamram
 
 ms.service: storage
 ms.topic: how-to
-ms.date: 11/26/2019
+ms.date: 01/03/2020
 ms.author: tamram
 ms.reviewer: cbrooks
 ms.subservice: common
diff --git a/articles/storage/common/storage-encryption-keys-cli.md b/articles/storage/common/storage-encryption-keys-cli.md
@@ -7,7 +7,7 @@ author: tamram
 
 ms.service: storage
 ms.topic: how-to
-ms.date: 12/04/2019
+ms.date: 01/03/2019
 ms.author: tamram
 ms.reviewer: cbrooks
 ms.subservice: common
@@ -19,10 +19,6 @@ ms.subservice: common
 
 This article shows how to configure an Azure Key Vault with customer-managed keys using Azure CLI. To learn how to create a key vault using  Azure CLI, see [Quickstart: Set and retrieve a secret from Azure Key Vault using Azure CLI](../../key-vault/quick-create-cli.md).
 
-> [!IMPORTANT]
-> Using customer-managed keys with Azure Storage encryption requires that two properties be set on the key vault, **Soft Delete** and **Do Not Purge**. These properties are not enabled by default. To enable these properties, use either PowerShell or Azure CLI.
-> Only RSA keys and key size 2048 are supported.
-
 ## Assign an identity to the storage account
 
 To enable customer-managed keys for your storage account, first assign a system-assigned managed identity to the storage account. You'll use this managed identity to grant the storage account permissions to access the key vault.
@@ -42,7 +38,7 @@ For more information about configuring system-assigned managed identities with A
 
 ## Create a new key vault
 
-The key vault that you use to store customer-managed keys for Azure Storage encryption must have two key protection settings enabled, **Soft Delete** and **Do Not Purge**. To create a new key vault using PowerShell or Azure CLI with these settings enabled, execute the following commands. Remember to replace the placeholder values in brackets with your own values. 
+The key vault that you use to store customer-managed keys for Azure Storage encryption must have two key protection settings enabled, **Soft Delete** and **Do Not Purge**. To create a new key vault using PowerShell or Azure CLI with these settings enabled, execute the following commands. Remember to replace the placeholder values in brackets with your own values.
 
 To create a new key vault using Azure CLI, call [az keyvault create](/cli/azure/keyvault#az-keyvault-create). Remember to replace the placeholder values in brackets with your own values.
 
@@ -55,6 +51,8 @@ az keyvault create \
     --enable-purge-protection
 ```
 
+To learn how to enable **Soft Delete** and **Do Not Purge** on an existing key vault with Azure CLI, see the sections titled **Enabling soft-delete** and **Enabling Purge Protection** in [How to use soft-delete with CLI](../../key-vault/key-vault-soft-delete-cli.md).
+
 ## Configure the key vault access policy
 
 Next, configure the access policy for the key vault so that the storage account has permissions to access it. In this step, you'll use the managed identity that you previously assigned to the storage account.
@@ -88,7 +86,7 @@ az keyvault key create
 
 By default, Azure Storage encryption uses Microsoft-managed keys. Configure your Azure Storage account for customer-managed keys and specify the key to associate with the storage account.
 
-To update the storage account's encryption settings, call [az storage account update](/cli/azure/storage/account#az-storage-account-update). This example also queries for the key vault URI and the latest key version, both of which values are needed to associate the key with the storage account. Remember to replace the placeholder values in brackets with your own values.
+To update the storage account's encryption settings, call [az storage account update](/cli/azure/storage/account#az-storage-account-update), as shown in the following example. Include the `--encryption-key-source` parameter and set it to `Microsoft.Keyvault` to enable customer-managed keys for the storage account. The example also queries for the key vault URI and the latest key version, both of which values are needed to associate the key with the storage account. Remember to replace the placeholder values in brackets with your own values.
 
 ```azurecli-interactive
 key_vault_uri=$(az keyvault show \
@@ -101,7 +99,7 @@ key_version=$(az keyvault key list-versions \
     --vault-name <key-vault> \
     --query [-1].kid \
     --output tsv | cut -d '/' -f 6)
-az storage account update 
+az storage account update
     --name <storage-account> \
     --resource-group <resource_group> \
     --encryption-key-name <key> \
@@ -114,6 +112,21 @@ az storage account update
 
 When you create a new version of a key, you'll need to update the storage account to use the new version. First, query for the key vault URI by calling [az keyvault show](/cli/azure/keyvault#az-keyvault-show), and for the key version by calling [az keyvault key list-versions](/cli/azure/keyvault/key#az-keyvault-key-list-versions). Then call [az storage account update](/cli/azure/storage/account#az-storage-account-update) to update the storage account's encryption settings to use the new version of the key, as shown in the previous section.
 
+## Use a different key
+
+To change the key used for Azure Storage encryption, call [az storage account update](/cli/azure/storage/account#az-storage-account-update) as shown in [Configure encryption with customer-managed keys](#configure-encryption-with-customer-managed-keys) and provide the new key name and version. If the new key is in a different key vault, also update the key vault URI.
+
+## Disable customer-managed keys
+
+When you disable customer-managed keys, your storage account is then encrypted with Microsoft-managed keys. To disable customer-managed keys, call [az storage account update](/cli/azure/storage/account#az-storage-account-update) and set the `--encryption-key-source parameter` to `Microsoft.Storage`, as shown in the following example. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.
+
+```powershell
+az storage account update
+    --name <storage-account> \
+    --resource-group <resource_group> \
+    --encryption-key-source Microsoft.Storage
+```
+
 ## Next steps
 
 - [Azure Storage encryption for data at rest](storage-service-encryption.md) 
diff --git a/articles/storage/common/storage-encryption-keys-portal.md b/articles/storage/common/storage-encryption-keys-portal.md
@@ -7,7 +7,7 @@ author: tamram
 
 ms.service: storage
 ms.topic: how-to
-ms.date: 12/04/2019
+ms.date: 01/02/2020
 ms.author: tamram
 ms.reviewer: cbrooks
 ms.subservice: common
@@ -19,9 +19,16 @@ ms.subservice: common
 
 This article shows how to configure an Azure Key Vault with customer-managed keys using the [Azure portal](https://portal.azure.com/). To learn how to create a key vault using the Azure portal, see [Quickstart: Set and retrieve a secret from Azure Key Vault using the Azure portal](../../key-vault/quick-create-portal.md).
 
-> [!IMPORTANT]
-> Using customer-managed keys with Azure Storage encryption requires that two properties be set on the key vault, **Soft Delete** and **Do Not Purge**. These properties are not enabled by default. To enable these properties, use either PowerShell or Azure CLI.
-> Only RSA keys and key size 2048 are supported.
+## Configure Azure Key Vault
+
+Using customer-managed keys with Azure Storage encryption requires that two properties be set on the key vault, **Soft Delete** and **Do Not Purge**. These properties are not enabled by default, but can be enabled using either PowerShell or Azure CLI on a new or existing key vault.
+
+To learn how to enable these properties on an existing key vault, see the sections titled **Enabling soft-delete** and **Enabling Purge Protection** 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 CLI](../../key-vault/key-vault-soft-delete-cli.md).
+
+Only RSA keys of size 2048 are supported with Azure Storage encryption. For more information about keys, see **Key Vault keys** in [About Azure Key Vault keys, secrets and certificates](../../key-vault/about-keys-secrets-and-certificates.md#key-vault-keys).
 
 ## Enable customer-managed keys
 
@@ -40,31 +47,53 @@ After you enable customer-managed keys, you'll have the opportunity to specify a
 
 To specify a key as a URI, follow these steps:
 
-1. To locate the key URI in the Azure portal, navigate to your key vault, and select the **Keys** setting. Select the desired key, then click the key to view its settings. Copy the value of the **Key Identifier** field, which provides the URI.
+1. To locate the key URI in the Azure portal, navigate to your key vault, and select the **Keys** setting. Select the desired key, then click the key to view its versions. Select a key version to view the settings for that version.
+1. Copy the value of the **Key Identifier** field, which provides the URI.
 
     ![Screenshot showing key vault key URI](media/storage-encryption-keys-portal/key-uri-portal.png)
 
 1. In the **Encryption** settings for your storage account, choose the **Enter key URI** option.
-1. In the **Key URI** field, specify the URI.
+1. Paste the URI that you copied into the **Key URI** field.
 
    ![Screenshot showing how to enter key URI](./media/storage-encryption-keys-portal/ssecmk2.png)
 
+1. Specify the subscription that contains the key vault.
+1. Save your changes.
+
 ### Specify a key from a key vault
 
 To specify a key from a key vault, first make sure that you have a key vault that contains a key. To specify a key from a key vault, follow these steps:
 
 1. Choose the **Select from Key Vault** option.
-2. Choose the key vault containing the key you want to use.
-3. Choose the key from the key vault.
+2. Select the key vault containing the key you want to use.
+3. Select the key from the key vault.
 
    ![Screenshot showing customer-managed key option](./media/storage-encryption-keys-portal/ssecmk3.png)
 
+1. Save your changes.
+
 ## Update the key version
 
-When you create a new version of a key, you'll need to update the storage account to use the new version. Follow these steps:
+When you create a new version of a key, update the storage account to use the new version. Follow these steps:
+
+1. Navigate to your storage account and display the **Encryption** settings.
+1. Enter the URI for the new key version. Alternately, you can select the key vault and the key again to update the version.
+1. Save your changes.
+
+## Use a different key
+
+To change the key used for Azure Storage encryption, follow these steps:
+
+1. Navigate to your storage account and display the **Encryption** settings.
+1. Enter the URI for the new key. Alternately, you can select the key vault and choose a new key.
+1. Save your changes.
+
+## Disable customer-managed keys
+
+When you disable customer-managed keys, your storage account is then encrypted with Microsoft-managed keys. To disable customer-managed keys, follow these steps:
 
 1. Navigate to your storage account and display the **Encryption** settings.
-1. Specify the URI for the new key version. Alternately, you can select the key vault and the key again to update the version.
+1. Deselect the checkbox next to the **Use your own key** setting.
 
 ## Next steps
 
diff --git a/articles/storage/common/storage-encryption-keys-powershell.md b/articles/storage/common/storage-encryption-keys-powershell.md
@@ -7,7 +7,7 @@ author: tamram
 
 ms.service: storage
 ms.topic: how-to
-ms.date: 12/04/2019
+ms.date: 01/03/2019
 ms.author: tamram
 ms.reviewer: cbrooks
 ms.subservice: common
@@ -19,10 +19,6 @@ ms.subservice: common
 
 This article shows how to configure an Azure Key Vault with customer-managed keys using PowerShell. To learn how to create a key vault using  Azure CLI, see [Quickstart: Set and retrieve a secret from Azure Key Vault using PowerShell](../../key-vault/quick-create-powershell.md).
 
-> [!IMPORTANT]
-> Using customer-managed keys with Azure Storage encryption requires that two properties be set on the key vault, **Soft Delete** and **Do Not Purge**. These properties are not enabled by default. To enable these properties, use either PowerShell or Azure CLI.
-> Only RSA keys and key size 2048 are supported.
-
 ## Assign an identity to the storage account
 
 To enable customer-managed keys for your storage account, first assign a system-assigned managed identity to the storage account. You'll use this managed identity to grant the storage account permissions to access the key vault.
@@ -39,9 +35,9 @@ For more information about configuring system-assigned managed identities with P
 
 ## Create a new key vault
 
-To create a new key vault using PowerShell, call [New-AzKeyVault](/powershell/module/az.keyvault/new-azkeyvault). The key vault that you use to store customer-managed keys for Azure Storage encryption must have two key protection settings enabled, **Soft Delete** and **Do Not Purge**. 
+To create a new key vault using PowerShell, call [New-AzKeyVault](/powershell/module/az.keyvault/new-azkeyvault). The key vault that you use to store customer-managed keys for Azure Storage encryption must have two key protection settings enabled, **Soft Delete** and **Do Not Purge**.
 
-Remember to replace the placeholder values in brackets with your own values. 
+Remember to replace the placeholder values in brackets with your own values.
 
 ```powershell
 $keyVault = New-AzKeyVault -Name <key-vault> `
@@ -51,6 +47,8 @@ $keyVault = New-AzKeyVault -Name <key-vault> `
     -EnablePurgeProtection
 ```
 
+To learn how to enable **Soft Delete** and **Do Not Purge** on an existing key vault with PowerShell, see the sections titled **Enabling soft-delete** and **Enabling Purge Protection** in [How to use soft-delete with PowerShell](../../key-vault/key-vault-soft-delete-powershell.md).
+
 ## Configure the key vault access policy
 
 Next, configure the access policy for the key vault so that the storage account has permissions to access it. In this step, you'll use the managed identity that you previously assigned to the storage account.
@@ -76,7 +74,7 @@ $key = Add-AzKeyVaultKey -VaultName $keyVault.VaultName -Name <key> -Destination
 
 By default, Azure Storage encryption uses Microsoft-managed keys. In this step, configure your Azure Storage account to use customer-managed keys and specify the key to associate with the storage account.
 
-Call [Set-AzStorageAccount](/powershell/module/az.storage/set-azstorageaccount) to update the storage account's encryption settings. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.
+Call [Set-AzStorageAccount](/powershell/module/az.storage/set-azstorageaccount) to update the storage account's encryption settings, as shown in the following example. Include the **-KeyvaultEncryption** option to enable customer-managed keys for the storage account. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.
 
 ```powershell
 Set-AzStorageAccount -ResourceGroupName $storageAccount.ResourceGroupName `
@@ -91,6 +89,20 @@ Set-AzStorageAccount -ResourceGroupName $storageAccount.ResourceGroupName `
 
 When you create a new version of a key, you'll need to update the storage account to use the new version. First, call [Get-AzKeyVaultKey](/powershell/module/az.keyvault/get-azkeyvaultkey) to get the latest version of the key. Then call [Set-AzStorageAccount](/powershell/module/az.storage/set-azstorageaccount) to update the storage account's encryption settings to use the new version of the key, as shown in the previous section.
 
+## Use a different key
+
+To change the key used for Azure Storage encryption, call [Set-AzStorageAccount](/powershell/module/az.storage/set-azstorageaccount) as shown in [Configure encryption with customer-managed keys](#configure-encryption-with-customer-managed-keys) and provide the new key name and version. If the new key is in a different key vault, also update the key vault URI.
+
+## Disable customer-managed keys
+
+When you disable customer-managed keys, your storage account is then encrypted with Microsoft-managed keys. To disable customer-managed keys, call [Set-AzStorageAccount](/powershell/module/az.storage/set-azstorageaccount) with the `-StorageEncryption` option, as shown in the following example. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.
+
+```powershell
+Set-AzStorageAccount -ResourceGroupName $storageAccount.ResourceGroupName `
+    -AccountName $storageAccount.StorageAccountName `
+    -StorageEncryption  
+```
+
 ## Next steps
 
 - [Azure Storage encryption for data at rest](storage-service-encryption.md)
diff --git a/articles/storage/common/storage-service-encryption.md b/articles/storage/common/storage-service-encryption.md
@@ -5,7 +5,7 @@ services: storage
 author: tamram
 
 ms.service: storage
-ms.date: 12/05/2019
+ms.date: 01/03/2020
 ms.topic: conceptual
 ms.author: tamram
 ms.reviewer: cbrooks
@@ -76,10 +76,12 @@ The following list explains the numbered steps in the diagram:
 
 ### Enable customer-managed keys for a storage account
 
-When you enable encryption with customer-managed keys for a storage account, Azure Storage wraps the account encryption key with the customer key in the associated key vault. Enabling customer-managed keys does not impact performance, and the account is encrypted with the new key immediately, without any time delay.
+When you enable encryption with customer-managed keys for a storage account, Azure Storage wraps the account encryption key with the customer-managed key in the associated key vault. Enabling customer-managed keys does not impact performance, and the account is encrypted with the new key immediately, without any time delay.
 
 A new storage account is always encrypted using Microsoft-managed keys. It's not possible to enable customer-managed keys at the time that the account is created. Customer-managed keys are stored in Azure Key Vault, and the key vault must be provisioned with access policies that grant key permissions to the managed identity that is associated with the storage account. The managed identity is available only after the storage account is created.
 
+When you modify the key being used for Azure Storage encryption by enabling or disabling customer-managed keys, updating the key version, or specifying a different key, then the encryption of the root key changes, but the data in your Azure Storage account does not need to be re-encrypted.
+
 To learn how to use customer-managed keys with Azure Key Vault for Azure Storage encryption, see one of these articles:
 
 - [Configure customer-managed keys with Key Vault for Azure Storage encryption from the Azure portal](storage-encryption-keys-portal.md)
@@ -93,6 +95,8 @@ To learn how to use customer-managed keys with Azure Key Vault for Azure Storage
 
 To enable customer-managed keys on a storage account, you must use an Azure Key Vault to store your keys. You must enable both the **Soft Delete** and **Do Not Purge** properties on the key vault.
 
+Only RSA keys of size 2048 are supported with Azure Storage encryption. For more information about keys, see **Key Vault keys** in [About Azure Key Vault keys, secrets and certificates](../../key-vault/about-keys-secrets-and-certificates.md#key-vault-keys).
+
 The key vault must be located in the same subscription as the storage account. Azure Storage uses managed identities for Azure resources to authenticate to the key vault for encryption and decryption operations. Managed identities do not currently support cross-directory scenarios.
 
 ### Rotate customer-managed keys
