Merge pull request #236601 from msmbaldwin/patch-191

Update tls-offload-library.md

Author: prmerger-automator[bot]

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

@@ -41,10 +41,14 @@ The TLS Offload Library includes a key creation tool, mhsm_p11_create_key. Runni
 
 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.
+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)
 
+For Managed Identities, the environment variables above are not needed. 
+- Use the `--identity` argument to enable managed identity with the mhsm_p11_create_key tool. 
+- The `client_id` of user-assigned managed identity should be cited in the MHSM configuration file (mhsm-pkcs11.conf). If the `client_id` of a user-assigned managed identity is not provided, it will consider it as system-assigned managed identity.
+
 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
@@ -70,7 +74,7 @@ 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 and Managed Identity.
 
 #### TLS Offload service principal
 
@@ -105,6 +109,15 @@ az keyvault role assignment create --hsm-name ContosoMHSM \
 --assignee [email protected]  \
 --scope /keys
 ```
+For Managed Identities,specify command arguments as follows:
+
+```azurecli
+az keyvault role assignment create --hsm-name ContosoMHSM \
+      --role "Managed HSM Crypto User"  \
+       --assignee-object-id <object_id>  \
+       --assignee-principal-type MSI \
+       --scope /keys
+```
 
 ### Granular approach
 
@@ -152,6 +165,30 @@ az keyvault role assignment create --hsm-name ContosoMHSM  \
 --assignee [email protected]  \
 --scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
 ```
+## Connection Caching
+
+To improve the performance of Sign calls to the Managed HSM Service, TLS Offload Library caches its TLS connections to the Managed HSM service servers. By default, TLS Offload Library caches up to 20 TLS connections.
+Connection Caching can be controlled through MHSM configuration file (mhsm-pkcs11.conf). 
+
+```json
+"ConnectionCache": {
+        "Disable": false, 
+        "MaxConnections": 20
+}
+```
+
+**Disable**
+
+If this value is true, Connection Caching will be disabled. It is enabled by default.
+
+**MaxConnections**
+
+Specifies maximum number of connections to cache. The maximum connection limit should be configured based on the number of concurrent PKCS11 sessions being used by the application. Applications typically create a pool of PKCS11 sessions and use them from a pool of threads to generate signing requests in parallel. The MaxConnections should match the number of concurrent signing requests generated by the applications.
+
+The Signing Request Per Second (RPS) is dependent on the number of concurrent requests and the number of connections cached. Specifying a higher number or even the default limit will not improve the signing RPS if the number of concurrent PKCS11 Signing requests is lower than this limit.
+The maximum number of concurrent connections to achieve burst mode of Standard B1 HSM pool is about 30 depending on the instance type. But you should try with different numbers to figure out the optimal number concurrent connections.
+
+Refer to your application documentation or contact your application vendor to learn more about how the application uses the PKCS11 library.
 
 ## Using the TLS Offload Library