Merge pull request #294085 from axisc/eventhubs-hsm-updates

adding hsm related docs for CMK

Author: prmerger-automator[bot]

articles/event-hubs/configure-customer-managed-key.md

@@ -6,18 +6,18 @@ ms.date: 05/13/2024
 ---
 
 # Configure customer-managed keys for encrypting Azure Event Hubs data at rest
-Azure Event Hubs provides encryption of data at rest with Azure Storage Service Encryption (Azure SSE). The Event Hubs service uses Azure Storage to store the data. All the data that's stored with Azure Storage is encrypted using Microsoft-managed keys. If you use your own key (also referred to as Bring Your Own Key (BYOK) or customer-managed key), the data is still encrypted using the Microsoft-managed key, but in addition the Microsoft-managed key will be encrypted using the customer-managed key. This feature enables you to create, rotate, disable, and revoke access to customer-managed keys that are used for encrypting Microsoft-managed keys. Enabling the BYOK feature is a one time setup process on your namespace.
+Azure Event Hubs provides encryption of data at rest with Azure Storage Service Encryption (Azure SSE). The Event Hubs service uses Azure Storage to store the data. All the data that's stored in Azure Storage is encrypted using Microsoft-managed keys. If you use your own key (also referred to as Bring Your Own Key (BYOK) or customer-managed key), the data is still encrypted using the Microsoft-managed key, but in addition the Microsoft-managed key will be encrypted using the customer-managed key. This feature enables you to create, rotate, disable, and revoke access to customer-managed keys that are used for encrypting Microsoft-managed keys. Enabling the BYOK feature is a one time setup process on your namespace.
 
 > [!IMPORTANT]
 > - The BYOK capability is supported by **premium** and **dedicated** tiers of Event Hubs.
-> - The encryption can be enabled only for new or empty namespaces. If the namespace contains event hubs, the encryption operation will fail.
+> - The encryption can be enabled only for new or empty namespaces. If the namespace contains event hubs, the encryption operation fails.
 
-You can use Azure Key Vault (including Azure Key Vault Managed HSM) to manage your keys and audit your key usage. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. For more information about Azure Key Vault, see [What is Azure Key Vault?](/azure/key-vault/general/overview)
+You can use Azure Key Vault (including Azure Key Vault Managed Hardware Security Module) to manage your keys and audit your key usage. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. For more information about Azure Key Vault, see [What is Azure Key Vault?](/azure/key-vault/general/overview)
 
 This article shows how to configure a key vault with customer-managed keys by using the Azure portal. To learn how to create a key vault using the Azure portal, see [Quickstart: Create an Azure Key Vault using the Azure portal](/azure/key-vault/general/quick-create-portal).
 
 ## Enable customer-managed keys (Azure portal)
-To enable customer-managed keys in the Azure portal, follow these steps. If you are using the dedicated tier, navigate to your Event Hubs Dedicated cluster first.
+To enable customer-managed keys in the Azure portal, follow these steps. If you're using the dedicated tier, navigate to your Event Hubs Dedicated cluster first.
 
 1. Select the namespace on which you want to enable BYOK.
 1. On the **Settings** page of your Event Hubs namespace, select **Encryption**. 
@@ -31,18 +31,21 @@ To enable customer-managed keys in the Azure portal, follow these steps. If you
 ## Set up a key vault with keys
 After you enable customer-managed keys, you need to associate the customer managed key with your Azure Event Hubs namespace. Event Hubs supports only Azure Key Vault. If you enable the **Encryption with customer-managed key** option in the previous section, you need to have the key imported into Azure Key Vault. Also, the keys must have **Soft Delete** and **Do Not Purge** configured for the key. These settings can be configured using [PowerShell](/azure/key-vault/general/key-vault-recovery) or [CLI](/azure/key-vault/general/key-vault-recovery).
 
-1. To create a new key vault, follow the Azure Key Vault [Quickstart](/azure/key-vault/general/overview). For more information about importing existing keys, see [About keys, secrets, and certificates](/azure/key-vault/general/about-keys-secrets-certificates).
+### Create key vault or key vault managed HSM
 
-    > [!IMPORTANT]
-    > Using customer-managed keys with Azure Event Hubs requires that the key vault have two required properties configured. They are:  **Soft Delete** and **Do Not Purge**. These properties are enabled by default when you create a new key vault in the Azure portal. However, if you need to enable these properties on an existing key vault, you must use either PowerShell or Azure CLI.
+> [!IMPORTANT]
+> Using customer-managed keys with Azure Event Hubs requires that the key vault have two required properties configured. They are:  **Soft Delete** and **Do Not Purge**. These properties are enabled by default when you create a new key vault in the Azure portal. However, if you need to enable these properties on an existing key vault, you must use either PowerShell or Azure CLI.
 
 # [Key Vault](#tab/Key-Vault)
 
+1. To create a new key vault, follow the Azure Key Vault [Quickstart](/azure/key-vault/general/overview). For more information about importing existing keys, see [About keys, secrets, and certificates](/azure/key-vault/general/about-keys-secrets-certificates).
+
 2. To turn on both soft delete and purge protection when creating a vault, use the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
 
    ```azurecli-interactive
    az keyvault create --name ContosoVault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true
    ```    
+
 3. To add purge protection to an existing vault (that already has soft delete enabled), use the [az keyvault update](/cli/azure/keyvault#az-keyvault-update) command.
 
    ```azurecli-interactive
@@ -51,38 +54,45 @@ After you enable customer-managed keys, you need to associate the customer manag
 
 # [Key Vault Managed HSM](#tab/Key-Vault-Managed-HSM)
 
+1. To create a new Managed HSM, follow the Managed HSM [Quickstart](/azure/key-vault/managed-hsm/quick-create-cli). For information about Azure KeyVault, see [About Azure KeyVault](/azure/key-vault/general/overview).
+
 2. To turn on both soft delete and purge protection when creating a vault, use the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
 
    ```azurecli-interactive
    az keyvault create --hsm-name ContosoVault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true
-   ```    
+   ```
+
+   After creation, you need to [activate the Managed HSM](/azure/key-vault/managed-hsm/quick-create-cli#activate-your-managed-hsm) and ensure that you have the correct permissions to generate keys by [assigning an RBAC role and local RBAC role](/azure/key-vault/managed-hsm/secure-your-managed-hsm) with the correct permissions.
+
 3. To add purge protection to an existing vault (that already has soft delete enabled), use the [az keyvault update](/cli/azure/keyvault#az-keyvault-update) command.
 
    ```azurecli-interactive
    az keyvault update --hsm-name ContosoVault --resource-group ContosoRG --enable-purge-protection true
    ```
 ---
 
-4. Create keys by following these steps:
-    1. To create a new key, select **Generate/Import** from the **Keys** menu under **Settings**.
+## Create Keys
+
+Create keys by following these steps:
+   1. To create a new key, select **Generate/Import** from the **Keys** menu under **Settings**.
 
         ![Select Generate/Import button](./media/configure-customer-managed-key/select-generate-import.png)
-    1. Set **Options** to **Generate** and give the key a name.
+   2. Set **Options** to **Generate** and give the key a name.
 
         ![Create a key](./media/configure-customer-managed-key/create-key.png) 
-    1. You can now select this key to associate with the Event Hubs namespace for encrypting from the drop-down list. 
+   3. You can now select this key to associate with the Event Hubs namespace for encrypting from the drop-down list. 
 
         ![Select key from key vault](./media/configure-customer-managed-key/select-key-from-key-vault.png)
 
         > [!NOTE]
-        > For redundancy, you can add up to 3 keys. In the event that one of the keys has expired, or is not accessible, the other keys will be used for encryption.
-    1. Fill in the details for the key and click **Select**. This will enable the encryption of the Microsoft-managed key with your key (customer-managed key). 
+        > For redundancy, you can add up to three keys. If one of the keys has expired, or isn't accessible, the other keys are used for encryption.
+   4. Fill in the details for the key and click **Select**. This enables the encryption of the Microsoft-managed key with your key (customer-managed key). 
 
 ## Managed identities
 There are two types of managed identities that you can assign to an Event Hubs namespace.
 
 - **System-assigned**: You can enable a managed identity directly on an Event Hubs namespace. When you enable a system-assigned managed identity, an identity is created in Microsoft Entra that's tied to the lifecycle of that Event Hubs namespace. So when the namespace is deleted, Azure automatically deletes the identity for you. By design, only that Azure resource (namespace) can use this identity to request tokens from Microsoft Entra ID.
-- **User-assigned**: You may also create a managed identity as a standalone Azure resource, which is called user-assigned identity. You can create a user-assigned managed identity and assign it to one or more Event Hubs namespaces. In the case of user-assigned managed identities, the identity is managed separately from the resources that use it. They are not tied to the lifecycle of the namespace. You can explicitly delete a user-assigned identity when you no longer need it.    
+- **User-assigned**: You can also create a managed identity as a standalone Azure resource, which is called user-assigned identity. You can create a user-assigned managed identity and assign it to one or more Event Hubs namespaces. In the case of user-assigned managed identities, the identity is managed separately from the resources that use it. They aren't tied to the lifecycle of the namespace. You can explicitly delete a user-assigned identity when you no longer need it.    
 
     For more information, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md).
 
@@ -215,7 +225,7 @@ You have done the following steps so far:
 1. Created a premium namespace with a managed identity.
 2. Create a key vault and granted the managed identity access to the key vault. 
 
-In this step, you will update the Event Hubs namespace with key vault information. 
+In this step, you'll update the Event Hubs namespace with key vault information. 
 
 1. Create a JSON file named **CreateEventHubClusterAndNamespace.json** with the following content: 
 
@@ -634,9 +644,9 @@ See the following example for using the user-managed identity for the encryption
 ## Enable infrastructure (or double) encryption of data
 If you require a higher level of assurance that your data is secure, you can enable infrastructure level encryption which is also known as Double Encryption. 
 
-When infrastructure encryption is enabled, data in the Event Hubs namespace account is encrypted twice, once at the service level and once at the infrastructure level, using two different encryption algorithms and two different keys. Hence, infrastructure encryption of Event Hubs data protects against a scenario where one of the encryption algorithms or keys may be compromised.
+When infrastructure encryption is enabled, data in the Event Hubs namespace account is encrypted twice, once at the service level and once at the infrastructure level, using two different encryption algorithms and two different keys. Hence, infrastructure encryption of Event Hubs data protects against a scenario where one of the encryption algorithms or keys can be compromised.
 
-You can enable infrastructure encryption by updating the Azure Resource Manager template with `requireInfrastructureEncryption` property in the above **CreateEventHubClusterAndNamespace.json** as shown below. 
+You can enable infrastructure encryption by updating the Azure Resource Manager template with `requireInfrastructureEncryption` property in the above **CreateEventHubClusterAndNamespace.json** as shown in the following example. 
 
 ```json
 "properties":{
@@ -659,15 +669,15 @@ You can enable infrastructure encryption by updating the Azure Resource Manager
 ## Rotate, revoke, and cache encryption keys
 
 ### Rotate your encryption keys
-You can rotate your key in the key vault by using the Azure Key Vaults rotation mechanism. Activation and expiration dates can also be set to automate key rotation. The Event Hubs service will detect new key versions and start using them automatically.
+You can rotate your key in the key vault by using the Azure Key Vaults rotation mechanism. Activation and expiration dates can also be set to automate key rotation. The Event Hubs service detects new key versions and start using them automatically.
 
 ### Revoke access to keys
 Revoking access to the encryption keys won't purge the data from Event Hubs. However, the data can't be accessed from the Event Hubs namespace. You can revoke the encryption key through access policy or by deleting the key. Learn more about access policies and securing your key vault from [Secure access to a key vault](/azure/key-vault/general/security-features).
 
-Once the encryption key is revoked, the Event Hubs service on the encrypted namespace will become inoperable. If the access to the key is enabled or the delete key is restored, Event Hubs service will pick the key so you can access the data from the encrypted Event Hubs namespace.
+Once the encryption key is revoked, the Event Hubs service on the encrypted namespace becomes inoperable. If the access to the key is enabled or the delete key is restored, Event Hubs service picks the key so you can access the data from the encrypted Event Hubs namespace.
 
 ### Caching of keys
-The Event Hubs instance (event hub) polls its listed encryption keys every 5 minutes. It caches and uses them until the next poll, which is after 5 minutes. As long as at least one key is available, the event hub is accessible. If all listed keys are inaccessible when it polls, all event hubs will become unavailable. 
+The Event Hubs instance (event hub) polls its listed encryption keys every 5 minutes. It caches and uses them until the next poll, which is after 5 minutes. As long as at least one key is available, the event hub is accessible. If all listed keys are inaccessible when it polls, all event hubs become unavailable. 
 
 Here are more details: 
 
@@ -686,12 +696,12 @@ To enable encryption of Microsoft-managed key with a customer managed key, an [a
 
 Due to this:
 
-- If [Geo disaster recovery](event-hubs-geo-dr.md) is already enabled for the Event Hubs namespace and you are looking to enable customer managed key, then
+- If [Geo disaster recovery](event-hubs-geo-dr.md) is already enabled for the Event Hubs namespace and you're looking to enable customer managed key, then
     - Break the pairing.
     - [Set up the access policy](/azure/key-vault/general/assign-access-policy-portal) for the system-assigned managed identity for both the primary and secondary namespaces to the key vault.
     - Set up encryption on the primary namespace.
     - Re-pair the primary and secondary namespaces.
-- If you are looking to enable Geo-DR on an Event Hubs namespace where customer-managed key is already set up, then follow these steps: 
+- If you're looking to enable Geo-DR on an Event Hubs namespace where customer-managed key is already set up, then follow these steps: 
     - [Set up the access policy](/azure/key-vault/general/assign-access-policy-portal) for the managed identity for the secondary namespace to the key vault.
     - Pair the primary and secondary namespaces.
 
@@ -704,8 +714,8 @@ Here are a few recommendations:
 
 Conditions for enabling Geo-DR and Encryption with User-Assigned Identities:
 
-1.	Secondary namespace must already have Encryption enabled with a User-Assigned identity if it is to be paired with a primary namespace that has Encryption enabled. 
-2.	It is not possible to enable Encryption on an already paired primary, even if the secondary has a User-Assigned identity associated with the namespace.
+1.	Secondary namespace must already have Encryption enabled with a User-Assigned identity if it's to be paired with a primary namespace that has Encryption enabled. 
+2.	It isn't possible to enable Encryption on an already paired primary, even if the secondary has a User-Assigned identity associated with the namespace.
 
 ## Set up diagnostic logs 
 Setting diagnostic logs for BYOK enabled namespaces gives you the required information about the operations. These logs can be enabled and later stream to an event hub or analyzed through log analytics or streamed to storage to perform customized analytics. To learn more about diagnostic logs, see [Overview of Azure Diagnostic logs](/azure/azure-monitor/essentials/platform-logs-overview). For the schema, see [Monitor data reference](monitor-event-hubs-reference.md#customer-managed-key-user-logs-schema).