Updates

Author: msmbaldwin

articles/key-vault/managed-hsm/tls-offload-library.md

@@ -6,15 +6,15 @@ author: msmbaldwin
 ms.service: key-vault
 ms.workload: identity
 ms.topic: conceptual
-ms.date: 02/20/2023
+ms.date: 02/25/2023
 ms.author: mbaldwin
 ---
 
 # Azure Managed HSM TLS Offload Library
 
-Azure Managed HSM offers a TLS Offload library, which is compliant with PKCS#11 version 2.40. We don't support all possible functions listed in the PKCS#11 specification. Our TLS Offload library supports a limited set of mechanisms and interface functions for SSL/TLS Offload with F5 (BigIP) and Nginx only, primarily to generate TLS server certificate keys and generate digital signatures during TLS handshakes.
+Azure Managed HSM offers a TLS Offload library, which is compliant with PKCS#11 version 2.40. Azure Managed HSM doesn't support all  functions listed in the PKCS#11 specification; instead, the TLS Offload library supports a limited set of mechanisms and interface functions for SSL/TLS Offload with F5 (BigIP) and Nginx only, primarily to generate TLS server certificate keys and generate digital signatures during TLS handshakes.
 
-For more information, [Azure Managed HSM TLS Offload Library GitHub](https://github.com/microsoft/AzureManagedHsmTLSOffload).
+For more information, see [Azure Managed HSM TLS Offload Library GitHub](https://github.com/microsoft/AzureManagedHsmTLSOffload).
 
 The TLS Offload Library internally uses the Azure Key Vault REST API to interact with Azure Managed HSM.
 
@@ -35,20 +35,21 @@ Applications that use the TLS Offload Library use one or more PKCS#11 attributes
 > [!WARNING]
 > Keys generated by the TLS Offload Library and their Tags are accessible over Azure Key Vault REST API. Manipulating these P11 Attribute Tags using Azure Key Vault REST API may break the TLS Offload Library applications.
 
-### Key Generation   
-The TLS Offload Library includes a key creation tool -  mhsm_p11_create_key. Running the tool without any command line arguments shows the correct usage of the tool.
+### Key Generation
 
-The key creation tool requires a Service Principal, which is assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
+The TLS Offload Library includes a key creation tool, mhsm_p11_create_key. Running the tool without any command line arguments shows the correct usage of the tool.
 
-The key creation tool reads the Service Principal credentials from the environment variables MHSM_CLIENT_ID and MHSM_CLIENT_SECRET.
-- MHSM_CLIENT_ID – must be set to the Service Principal's Application (Client) ID
-- MHSM_CLIENT_SECRET – must be set to the Service Principal's Password (Client Secret)
+The key creation tool requires a service principal, which is assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
 
-The key creation tool randomly generates a name for the key at the time of creation. The full Azure Key Vault Key ID and the Key Name are printed to the console for your convenience.
+The key creation tool reads the service principal credentials from the environment variables MHSM_CLIENT_ID and MHSM_CLIENT_SECRET.
+- MHSM_CLIENT_ID – must be set to the service principal's application (client) ID
+- MHSM_CLIENT_SECRET – must be set to the service principal's password (client secret)
+
+The key creation tool randomly generates a name for the key at the time of creation. The full Azure Key Vault key ID and the key name are printed to the console for your convenience.
 
 ```azurepowershell
-MHSM_CLIENT_ID="Service Principal Application Id" \
-MHSM_CLIENT_SECRET="Service Principal Password" \
+MHSM_CLIENT_ID="<service-principal-application-id>" \
+MHSM_CLIENT_SECRET="<service-principal-password>" \
 mhsm_p11_create_key --RSA 4K --label tlsKey
 
 Key is generated successfully. \
@@ -69,12 +70,12 @@ For more information on Azure Managed HSM local RBAC, see:
 - [Azure Managed HSM local RBAC built-in roles](built-in-roles.md)
 - [Azure Managed HSM role management](role-management.md)
 
-The following section describes different approaches to implement access control for the TLS Offload Library Service Principal.
+The following section describes different approaches to implement access control for the TLS Offload Library service principal.
 
-#### TLS Offload Service Principal
+#### TLS Offload service principal
 
-The TLS Offload Service Principal is used by the application that uses TLS Offload Library to access keys. This Service Principal should have at minimum the following permission via role assignments:
-- KeyRead permission to all the keys in the Managed HSM
+The TLS Offload service principal is used by the application that uses TLS Offload Library to access keys, and should have at minimum the following permission via role assignments:
+- KeyRead permission to all the keys in the managed HSM
 - KeySign permission to the keys necessary for TLS offloading
 
 #### Admin User
@@ -86,7 +87,7 @@ The Admin User will create a custom role definition and role assignments. Hence,
 
 #### Key generation service principal
 
-The key generation service principal is used with the key creation tool (mhsm_p11_create_key) to generate TLS offload keys. This Service Principal should be assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
+The key generation service principal is used with the key creation tool (mhsm_p11_create_key) to generate TLS offload keys. This service principal should be assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
 
 #### Azure CLI
 
@@ -96,7 +97,7 @@ Azure CLI can be used to perform tasks such as Role Assignment.
 
 The permissive approach is simpler, and suitable when the Azure Managed HSM is exclusively used for TLS offloading.
 
-Assign the Crypto User role to TLS Offload Service Principal at the "/keys" scope. This gives the TLS Offload Service Principal the permission to generate keys and find them for TLS Offloading.
+Assign the Crypto User role to TLS Offload service principal at the "/keys" scope. This gives the TLS Offload service principal the permission to generate keys and find them for TLS Offloading.
 
 ```azurecli
 az keyvault role assignment create --hsm-name ContosoMHSM \
@@ -107,13 +108,13 @@ az keyvault role assignment create --hsm-name ContosoMHSM \
 
 ### Granular Approach
 
-The granular approach implements fine grained access control. It requires two Service Principals (TLS Offload Service Principal and Key Generation Service Principal) and an Admin User.
+The granular approach implements fine grained access control. It requires two service principals (TLS Offload service principal and Key Generation service principal) and an Admin User.
 
-The objective is to restrict the TLS Offload Service Principal's permissions to support the minimum required for TLS offload. The user must have the Read permission for other keys to support the library's C_FindObject* function.
+The objective is to restrict the TLS Offload service principal's permissions to support the minimum required for TLS offload. The user must have the Read permission for other keys to support the library's C_FindObject* function.
 
 #### TLS Offload Library User Read Role
 
-The first step in implementing the granular approach is to create a custom role. This is a one-time operation.
+The first step in implementing the granular approach is to create a custom role. This operation only needs to be done once.
 
 The Admin User (with Managed HSM Crypto Officer or Managed HSM Administrator or Managed HSM Policy Administrator role) creates a custom "TLS Library User Read Role" role definition:
 
@@ -130,11 +131,11 @@ az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
 
 #### Generate Keys
 
-Keys can be generated using the Key Generation Service Principal with the key creation tool (mhsm_p11_create_key).
+Keys can be generated using the Key Generation service principal with the key creation tool (mhsm_p11_create_key).
 
 #### Grant Permission
 
-The Admin User assigns the following roles to the TLS Offload Service Principal.
+The Admin User assigns the following roles to the TLS Offload service principal.
 - Assign "TLS Library User Read Role" role at the "/keys" scope
 - Assign "Managed HSM Crypto User" role at the "/keys/{key name}" scope
 
@@ -158,17 +159,17 @@ az keyvault role assignment create --hsm-name ContosoMHSM  \
 
 The TLS Offload Library includes a key creation tool -  mhsm_p11_create_key. Running the tool without any command line arguments shows the correct usage of the tool.
 
-The key creation tool requires a Service Principal, which is assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
+The key creation tool requires a service principal, which is assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
 
-The key creation tool reads the Service Principal credentials from the environment variables MHSM_CLIENT_ID and MHSM_CLIENT_SECRET.
-- MHSM_CLIENT_ID – must be set to the Service Principal's Application (Client) ID
-- MHSM_CLIENT_SECRET – must be set to the Service Principal's Password (Client Secret)
+The key creation tool reads the service principal credentials from the environment variables MHSM_CLIENT_ID and MHSM_CLIENT_SECRET.
+- MHSM_CLIENT_ID – must be set to the service principal's application (client) ID
+- MHSM_CLIENT_SECRET – must be set to the service principal's password (client secret)
 
 The key creation tool randomly generates a name for the key at the time of creation. The full Azure Key Vault Key ID and the Key Name are printed to the console for your convenience.
 
 ```azurepowershell
-MHSM_CLIENT_ID="Service Principal Application Id" \
-MHSM_CLIENT_SECRET="Service Principal Password" \
+MHSM_CLIENT_ID="<service-principal-application-id>" \
+MHSM_CLIENT_SECRET="<service-principal-password>" \
 mhsm_p11_create_key --RSA 4K --label tlsKey
 
 Key is generated successfully.
@@ -186,8 +187,8 @@ There are two approaches to generating a key and using the key for the Key Less
 
 #### Simpler approach
 
-1. Create a Service Principal for the TLS Offload Library (for example, TLSOffload ServicePrincipal)
-2. Assign "Managed HSM Crypto User" role to the TLS Offload Service Principal at the "/keys" scope.
+1. Create a service principal for the TLS Offload Library (for example, TLSOffload ServicePrincipal)
+2. Assign "Managed HSM Crypto User" role to the TLS Offload service principal at the "/keys" scope.
     ```azurecli
     az keyvault role assignment create --hsm-name ContosoMHSM \
     --role "Managed HSM Crypto User"  \
@@ -196,15 +197,15 @@ There are two approaches to generating a key and using the key for the Key Less
     ```
 3. Generate key with required label following the steps in [How to generate keys using the TLS Offload Library](#how-to-generate-keys-using-the-tls-offload-library).
 4. Configure the TLS server to use the Managed HSM TLS Offload Library as the PKCS#11 interface library
-5. Configure the TLS server (for example, the nginx SSL configuration setting `ssl_certificate_key') with the key label and the TLS Offload Service Principal credentials
+5. Configure the TLS server (for example, the nginx SSL configuration setting `ssl_certificate_key') with the key label and the TLS Offload service principal credentials
 
 #### Granular approach
 
 1. Create an Admin User (for example, TLSOffloadAdminUser) with the following role:
   - "Managed HSM Crypto Officer" role at the "/" scope
-1. Create a Key Generation Service Principal (for example, TLSOffloadKeyGenServicePrincipal) for the TLS Offload Key generation and assign the following role:
+1. Create a Key Generation service principal (for example, TLSOffloadKeyGenServicePrincipal) for the TLS Offload Key generation and assign the following role:
   - "Managed HSM Crypto User" role at the "/keys" scope.
-1. Create a Service Principal for the TLS Offloading (for example, TLSOffload   ServicePrincipal)
+1. Create a service principal for the TLS Offloading (for example, TLSOffload   ServicePrincipal)
 1. The Admin User creates the following custom role definition:
     ```azurecli
     az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
@@ -216,10 +217,10 @@ There are two approaches to generating a key and using the key for the Key Less
     "notDataActions": []
     }'
     ```
-1. Generate a key with required label following "How to generate keys using the TLS Offload Library". Use the Key Generation Service Principal (for example, TLSOffloadKeyGenServicePrincipal) while generating keys. Note down the Key Label and Key Name. For example:
+1. Generate a key with required label following "How to generate keys using the TLS Offload Library". Use the Key Generation service principal (for example, TLSOffloadKeyGenServicePrincipal) while generating keys. Note down the Key Label and Key Name. For example:
   - Key Label: tlsKey
   - Key Name: p11-6a2155dc40c94367a0f97ab452dc216f  
-1. Admin User assigns the following roles to the TLS Offload Service Principal
+1. Admin User assigns the following roles to the TLS Offload service principal
   - "TLS Library User Read Role" role at the "/keys" scope
   - "Managed HSM Crypto User" role at the "/keys/{key name}" scope
     ```azurecli
@@ -233,8 +234,8 @@ There are two approaches to generating a key and using the key for the Key Less
     --assignee [email protected]  \
     --scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
     ```
-1. Configure the TLS server to use the Managed HSM TLS Offload Library as the PKCS#11 interface library
-1. Configure the TLS server (for example, the nginx SSL configuration setting `ssl_certificate_key') with the key label and the TLS Offload Service Principal credentials
+1. Configure the TLS server to use the Azure Managed HSM TLS Offload Library as the PKCS#11 interface library
+1. Configure the TLS server (for example, the nginx SSL configuration setting `ssl_certificate_key') with the key label and the TLS Offload service principal credentials
 
 ## Next steps