Updates

Author: msmbaldwin

articles/key-vault/managed-hsm/access-control.md

@@ -8,7 +8,7 @@ tags: azure-resource-manager
 ms.service: key-vault
 ms.subservice: managed-hsm
 ms.topic: conceptual
-ms.date: 02/17/2021
+ms.date: 01/04/2023
 ms.author: mbaldwin
 # Customer intent: As the admin for managed HSMs, I want to set access policies and configure the Managed HSM, so that I can ensure it's secure and auditors can properly monitor all activities for these managed HSMs.
 ---
@@ -22,26 +22,26 @@ Azure Key Vault Managed HSM is a cloud service that safeguards encryption keys.
 
 ## Access control model
 
-Access to a managed HSM is controlled through two interfaces: the **management plane** and the **data plane**. The management plane is where you manage the HSM itself. Operations in this plane include creating and deleting managed HSMs and retrieving managed HSM properties. The data plane is where you work with the data stored in an managed HSM -- that is HSM-backed encryption keys. You can add, delete, modify, and use keys to perform cryptographic operations, manage role assignments to control access to the  keys, create a full HSM backup, restore full backup, and manage security domain from the data plane interface.
+Access to a managed HSM is controlled through two interfaces: the **management plane** and the **data plane**. The management plane is where you manage the HSM itself. Operations in this plane include creating and deleting managed HSMs and retrieving managed HSM properties. The data plane is where you work with the data stored in a managed HSM — that is, the HSM-backed encryption keys. You can add, delete, modify, and use keys to perform cryptographic operations, manage role assignments to control access to the  keys, create a full HSM backup, restore full backup, and manage security domain from the data plane interface.
 
 To access a managed HSM in either plane, all callers must have proper authentication and authorization. Authentication establishes the identity of the caller. Authorization determines which operations the caller can execute. A caller can be any one of the [security principals](../../role-based-access-control/overview.md#security-principal) defined in Azure Active Directory - user, group, service principal or managed identity.
 
-Both planes use Azure Active Directory for authentication. For authorization they use different systems as follows
-- The management plane uses Azure role-based access control -- Azure RBAC -- an authorization system built on Azure Azure Resource Manager 
-- The data plane uses a managed HSM-level RBAC (Managed HSM local RBAC) -- an authorization system implemented and enforced at the managed HSM level.
+Both planes use Azure Active Directory for authentication. For authorization, they use different systems as follows
+- The management plane uses Azure role-based access control (Azure RBAC), an authorization system built on Azure Resource Manager 
+- The data plane uses a managed HSM-level RBAC (Managed HSM local RBAC), an authorization system implemented and enforced at the managed HSM level.
 
 When a managed HSM is created, the requestor also provides a list of data plane administrators (all [security principals](../../role-based-access-control/overview.md#security-principal) are supported). Only these administrators are able to access the managed HSM data plane to perform key operations and manage data plane role assignments (Managed HSM local RBAC).
 
-Permission model for both planes uses the same syntax, but they are enforced at different levels and role assignments use different scopes. Management plane Azure RBAC is enforced by Azure Resource Manager while data plane Managed HSM local RBAC is enforced by managed HSM itself.
+Permission model for both planes uses the same syntax, but they're enforced at different levels and role assignments use different scopes. Management plane Azure RBAC is enforced by Azure Resource Manager while data plane Managed HSM local RBAC is enforced by managed HSM itself.
 
 > [!IMPORTANT]
 > Granting a security principal management plane access to an managed HSM does not grant them any access to data plane to access keys or data plane role assignments Managed HSM local RBAC). This isolation is by design to prevent inadvertent expansion of privileges affecting access to keys stored in Managed HSM.
 
-For example, a subscription administrator (since they have "Contributor" permission to all resources in the subscription) can delete an managed HSM in their subscription, but if they don't have data plane access specifically granted through Managed HSM local RBAC, they cannot gain access to keys or manage role assignment in the managed HSM to grant themselves or others access to data plane.
+For example, a subscription administrator (since they have "Contributor" permission to all resources in the subscription) can delete an managed HSM in their subscription, but if they don't have data plane access specifically granted through Managed HSM local RBAC, they can't gain access to keys or manage role assignment in the managed HSM to grant themselves or others access to data plane.
 
 ## Azure Active Directory authentication
 
-When you create an managed HSM in an Azure subscription, it's automatically associated with the Azure Active Directory tenant of the subscription. All callers in both planes must be registered in this tenant and authenticate to access the managed HSM.
+When you create a managed HSM in an Azure subscription, it's automatically associated with the Azure Active Directory tenant of the subscription. All callers in both planes must be registered in this tenant and authenticate to access the managed HSM.
 
 The application authenticates with Azure Active Directory before calling either plane. The application can use any [supported authentication method](../../active-directory/develop/authentication-vs-authorization.md) based on the application type. The application acquires a token for a resource in the plane to gain access. The resource is an endpoint in the management or data plane, based on the Azure environment. The application uses the token and sends a REST API request to Managed HSM endpoint. To learn more, review the [whole authentication flow](../../active-directory/develop/v2-oauth2-auth-code-flow.md).
 
@@ -53,7 +53,7 @@ The use of a single authentication mechanism for both planes has several benefit
 
 ## Resource endpoints
 
-Security principals access the planes through endpoints. The access controls for the two planes work independently. To grant an application access to use keys in an managed HSM, you grant data plane access by using Managed HSM local RBAC. To grant a user access to Managed HSM resource to create, read, delete, move the managed HSMs and edit other properties and tags you use Azure RBAC.
+Security principals access the planes through endpoints. The access controls for the two planes work independently. To grant an application access to use keys in a managed HSM, you grant data plane access by using Managed HSM local RBAC. To grant a user access to Managed HSM resource to create, read, delete, move the managed HSMs and edit other properties and tags you use Azure RBAC.
 
 The following table shows the endpoints for the management and data planes.
 
@@ -78,7 +78,7 @@ There are several predefined roles. If a predefined role doesn't fit your needs,
 
 ## Data plane and Managed HSM local RBAC
 
-You grant a security principal access to execute specific key operations by assigning a role. For each role assignment you need to specify a role and scope over which that assignment applies. For Managed HSM local RBAC two scopes are available.
+You grant a security principal access to execute specific key operations by assigning a role. For each role assignment, you must specify a role and scope over which that assignment applies. For Managed HSM local RBAC two scopes are available.
 
 - **"/" or "/keys"**: HSM level scope. Security principals assigned a role at this scope can perform the operations defined in the role for all objects (keys) in the managed HSM.
 - **"/keys/<key-name>"**: Key level scope. Security principals assigned a role at this scope can perform the operations defined in this role for all versions of the specified key only.

articles/key-vault/managed-hsm/backup-restore.md

@@ -8,7 +8,7 @@ tags: azure-key-vault
 ms.service: key-vault
 ms.subservice: managed-hsm
 ms.topic: tutorial
-ms.date: 09/15/2020
+ms.date: 01/04/2023
 ms.author: mbaldwin
 # Customer intent: As a developer using Key Vault I want to know the best practices so I can implement them.
 ---
@@ -75,7 +75,7 @@ You must provide the following information to execute a full restore:
 - Storage account name
 - Storage account blob container
 - Storage container SAS token with permissions `rl`
-- Storage container folder name where the source backup is store
+- Storage container folder name where the source backup is stored
 
 Restore is a long running operation but will immediately return a Job ID. You can check the status of the restore process using this Job ID. When the restore process is in progress, the HSM enters a restore mode and all data plane command (except check restore status) are disabled.
 

articles/key-vault/managed-hsm/best-practices.md

@@ -8,7 +8,7 @@ tags: azure-key-vault
 ms.service: key-vault
 ms.subservice: managed-hsm
 ms.topic: conceptual
-ms.date: 06/21/2021
+ms.date: 01/04/2023
 ms.author: mbaldwin
 # Customer intent: As a developer using Managed HSM I want to know the best practices so I can implement them.
 ---
@@ -17,10 +17,10 @@ ms.author: mbaldwin
 ## Control Access to your managed HSM
 
 Managed HSM is a cloud service that safeguards encryption keys. As these keys are sensitive and business critical, make sure to secure access to your managed HSMs by allowing only authorized applications and users. This [article](access-control.md) provides an overview of the access model. It explains authentication and authorization, and role-based access control.
-- Create an [Azure Active Directory Security Group](../../active-directory/fundamentals/active-directory-manage-groups.md) for the HSM Administrators (instead of assigning Administrator role to individuals). This will prevent "administration lock-out" in case of individual account deletion.
+- Create an [Azure Active Directory Security Group](../../active-directory/fundamentals/active-directory-manage-groups.md) for the HSM Administrators (instead of assigning Administrator role to individuals), to prevent "administration lock-out" if there was individual account deletion.
 - Lock down access to your management groups, subscriptions, resource groups and Managed HSMs - Use Azure RBAC to control access to your management groups, subscriptions, and resource groups
 - Create per key role assignments using [Managed HSM local RBAC](access-control.md#data-plane-and-managed-hsm-local-rbac).
-- To maintain separation of duties avoid assigning multiple roles to same principals.
+- To maintain separation of duties, avoid assigning multiple roles to same principals.
 - Use least privilege access principal to assign roles.
 - Create custom role definition with precise set of permissions.
 

articles/key-vault/managed-hsm/built-in-roles.md

@@ -7,7 +7,7 @@ author: mbaldwin
 ms.service: key-vault
 ms.subservice: managed-hsm
 ms.topic: tutorial
-ms.date: 06/01/2021
+ms.date: 01/04/2023
 ms.author: mbaldwin
 
 ---
@@ -30,7 +30,7 @@ Managed HSM local RBAC has several built-in roles. You can assign these roles to
 ## Permitted operations
 > [!NOTE]  
 > - An 'X' indicates that a role is allowed to perform the data action. Empty cell indicates the role does not have pemission to perform that data action.
-> - All the data action names have a 'Microsoft.KeyVault/managedHsm' prefix, which is omitted in the tables below for brevity.
+> - All the data action names have a 'Microsoft.KeyVault/managedHsm' prefix, which is omitted in the tables for brevity.
 > - All role names have a prefix "Managed HSM" which is omitted in the below table for brevity.
 
 |Data Action | Administrator | Crypto Officer | Crypto User | Policy Administrator | Crypto Service Encryption | Backup | Crypto Auditor|

articles/key-vault/managed-hsm/index.yml

@@ -12,7 +12,7 @@ metadata:
   author: msmbaldwin
   ms.author: mbaldwin
   manager: rkarlin
-  ms.date: 09/15/2020
+  ms.date: 01/04/2023
 
 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new