Skip to content

Commit 5248810

Browse files
Maggiemouse1Maggiemouse1
authored
Merge pull request #228331 from msmbaldwin/dhsm-misc
Added Azure Managed HSM TLS Offload Library article
2 parents 439bd07 + 67b7b57 commit 5248810

File tree

2 files changed

+246
-0
lines changed

2 files changed

+246
-0
lines changed

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

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
title: Azure Managed HSM TLS Offload Library
3+
description: Azure Managed HSM TLS Offload Library
4+
services: key-vault
5+
author: msmbaldwin
6+
ms.service: key-vault
7+
ms.workload: identity
8+
ms.topic: conceptual
9+
ms.date: 02/25/2023
10+
ms.author: mbaldwin
11+
---
12+
13+
# Azure Managed HSM TLS Offload Library
14+
15+
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.
16+
17+
For more information, see [Azure Managed HSM TLS Offload Library GitHub](https://github.com/microsoft/AzureManagedHsmTLSOffload).
18+
19+
The TLS Offload Library internally uses the Azure Key Vault REST API to interact with Azure Managed HSM.
20+
21+
## Get started
22+
23+
### PKCS#11 attributes
24+
25+
To properly integrate with PKCS#11, generating keys (via C_GenerateKeyPair) and locating key objects (via C_FindObjectsInit/C_FindObjects) requires a solution for storing PKCS#11 attributes on the Azure Key Vault key object. The TLS Offload Library converts these necessary PKCS#11 attributes into Azure Key Vault Tags.
26+
27+
These "Attribute Tags" have a special prefix:
28+
- p11_pri_{P11 Attribute Name} - Private Key Attributes
29+
- p11_pub_{P11 Attribute Name} - Public Key Attributes
30+
31+
The TLS Offload library properly sets the Azure Key Vault Key Operations and Key Lifetime attributes so the service can properly enforce these restrictions on the generated keys. These attributes are also stored as tags like other PKCS#11 attributes to support query capabilities.
32+
33+
Applications that use the TLS Offload Library use one or more PKCS#11 attributes to locate and use the key objects.
34+
35+
> [!WARNING]
36+
> 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.
37+
38+
### Key generation
39+
40+
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.
41+
42+
The key creation tool requires a service principal, which is assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
43+
44+
The key creation tool reads the service principal credentials from the environment variables MHSM_CLIENT_ID and MHSM_CLIENT_SECRET.
45+
- MHSM_CLIENT_ID – must be set to the service principal's application (client) ID
46+
- MHSM_CLIENT_SECRET – must be set to the service principal's password (client secret)
47+
48+
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.
49+
50+
```azurepowershell
51+
MHSM_CLIENT_ID="<service-principal-application-id>" \
52+
MHSM_CLIENT_SECRET="<service-principal-password>" \
53+
mhsm_p11_create_key --RSA 4K --label tlsKey
54+
55+
Key is generated successfully. \
56+
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
57+
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f
58+
```
59+
60+
The `--label` argument to the key creation tool specifies the desired CKA_LABEL for the private and public keys generated. These attributes are typically required to configure supported TLS Offload solutions (for example, the nginx SSL configuration setting `ssl_certificate_key').
61+
62+
You need the key name for any role assignment changes via the Azure CLI.
63+
64+
### Access control
65+
66+
The TLS Offload Library translates the C_FindObjectsInit into an Azure Key Vault REST API call, which operates at the /keys scope. The MHSM service requires the Read permission at this scope for the TLS Offload Library User to authorize the find operation for the keys created via the key creation tool.
67+
68+
For more information on Azure Managed HSM local RBAC, see:
69+
70+
- [Azure Managed HSM local RBAC built-in roles](built-in-roles.md)
71+
- [Azure Managed HSM role management](role-management.md)
72+
73+
The following section describes different approaches to implement access control for the TLS Offload Library service principal.
74+
75+
#### TLS Offload service principal
76+
77+
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:
78+
- KeyRead permission to all the keys in the managed HSM
79+
- KeySign permission to the keys necessary for TLS offloading
80+
81+
#### Admin User
82+
83+
The Admin User will create a custom role definition and role assignments. Hence, the Admin User should be assigned to one of the following Built-in roles at the "/" scope:
84+
- Managed HSM Crypto Officer
85+
- Managed HSM Policy Administrator
86+
- Managed HSM Administrator
87+
88+
#### Key generation service principal
89+
90+
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.
91+
92+
#### Azure CLI
93+
94+
Azure CLI can be used to perform tasks such as role assignment.
95+
96+
### Permissive approach
97+
98+
The permissive approach is simpler, and suitable when the Azure Managed HSM is exclusively used for TLS offloading.
99+
100+
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.
101+
102+
```azurecli
103+
az keyvault role assignment create --hsm-name ContosoMHSM \
104+
--role "Managed HSM Crypto User" \
105+
--assignee [email protected] \
106+
--scope /keys
107+
```
108+
109+
### Granular approach
110+
111+
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.
112+
113+
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.
114+
115+
#### TLS Offload Library User Read role
116+
117+
The first step in implementing the granular approach is to create a custom role. This operation only needs to be done once.
118+
119+
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:
120+
121+
```azurecli
122+
az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
123+
"roleName": "TLS Library User Read Role", \
124+
"description": "Grant Read access to keys", \
125+
"actions": [], \
126+
"notActions": [], \
127+
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
128+
"notDataActions": [] \
129+
}'
130+
```
131+
132+
#### Generate keys
133+
134+
Keys can be generated using the Key Generation service principal with the key creation tool (mhsm_p11_create_key).
135+
136+
#### Grant permission
137+
138+
The Admin User assigns the following roles to the TLS Offload service principal.
139+
- Assign "TLS Library User Read Role" role at the "/keys" scope
140+
- Assign "Managed HSM Crypto User" role at the "/keys/{key name}" scope
141+
142+
In the following example, the key name is "p11-6a2155dc40c94367a0f97ab452dc216f".
143+
144+
```azurecli
145+
az keyvault role assignment create --hsm-name ContosoMHSM \
146+
--role "TLS Library User Read Role" \
147+
--assignee [email protected] \
148+
--scope /keys
149+
150+
az keyvault role assignment create --hsm-name ContosoMHSM \
151+
--role "Managed HSM Crypto User" \
152+
--assignee [email protected] \
153+
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
154+
```
155+
156+
## Using the TLS Offload Library
157+
158+
### Generate keys
159+
160+
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.
161+
162+
The key creation tool requires a service principal, which is assigned to the "Managed HSM Crypto User" role at the "/keys" scope.
163+
164+
The key creation tool reads the service principal credentials from the environment variables MHSM_CLIENT_ID and MHSM_CLIENT_SECRET.
165+
- MHSM_CLIENT_ID – must be set to the service principal's application (client) ID
166+
- MHSM_CLIENT_SECRET – must be set to the service principal's password (client secret)
167+
168+
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.
169+
170+
```azurepowershell
171+
MHSM_CLIENT_ID="<service-principal-application-id>" \
172+
MHSM_CLIENT_SECRET="<service-principal-password>" \
173+
mhsm_p11_create_key --RSA 4K --label tlsKey
174+
175+
Key is generated successfully.
176+
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
177+
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f
178+
```
179+
180+
The `--label` argument to the key creation tool specifies the desired CKA_LABEL for the private and public keys generated. These attributes are typically required to configure supported TLS Offload solutions (for example, the nginx SSL configuration setting `ssl_certificate_key').
181+
182+
The key name is required if you're planning to implement granular access to keys.
183+
184+
### Implement keyless TLS
185+
186+
There are two approaches to generating a key and using the key for the Key Less TLS: a simpler, more permissive approach, and a granular approach, which offers better security. The approaches differ in implementation effort and security enforcement.
187+
188+
#### Simpler approach
189+
190+
1. Create a service principal for the TLS Offload Library (for example, TLSOffload ServicePrincipal)
191+
2. Assign "Managed HSM Crypto User" role to the TLS Offload service principal at the "/keys" scope.
192+
```azurecli
193+
az keyvault role assignment create --hsm-name ContosoMHSM \
194+
--role "Managed HSM Crypto User" \
195+
--assignee [email protected] \
196+
--scope /keys
197+
```
198+
3. Generate key with required label following the steps in [How to generate keys using the TLS Offload Library](#generate-keys).
199+
4. Configure the TLS server to use the Managed HSM TLS Offload Library as the PKCS#11 interface library
200+
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
201+
202+
#### Granular approach
203+
204+
1. Create an Admin User (for example, TLSOffloadAdminUser) with the following role:
205+
- "Managed HSM Crypto Officer" role at the "/" scope
206+
1. Create a Key Generation service principal (for example, TLSOffloadKeyGenServicePrincipal) for the TLS Offload Key generation and assign the following role:
207+
- "Managed HSM Crypto User" role at the "/keys" scope.
208+
1. Create a service principal for the TLS Offloading (for example, TLSOffload ServicePrincipal)
209+
1. The Admin User creates the following custom role definition:
210+
```azurecli
211+
az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
212+
"roleName": "TLS Library User Read Role", \
213+
"description": "Grant Read access to keys", \
214+
"actions": [], \
215+
"notActions": [], \
216+
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
217+
"notDataActions": []
218+
}'
219+
```
220+
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:
221+
- Key Label: tlsKey
222+
- Key Name: p11-6a2155dc40c94367a0f97ab452dc216f
223+
1. Admin User assigns the following roles to the TLS Offload service principal
224+
- "TLS Library User Read Role" role at the "/keys" scope
225+
- "Managed HSM Crypto User" role at the "/keys/{key name}" scope
226+
```azurecli
227+
az keyvault role assignment create --hsm-name ContosoMHSM \
228+
--role " TLS Library User Read Role" \
229+
--assignee TLSOffloadServicePrincipal @contoso.com \
230+
--scope /keys
231+
232+
az keyvault role assignment create --hsm-name ContosoMHSM \
233+
--role "Managed HSM Crypto User" \
234+
--assignee [email protected] \
235+
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
236+
```
237+
1. Configure the TLS server to use the Azure Managed HSM TLS Offload Library as the PKCS#11 interface library
238+
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
239+
240+
## Next steps
241+
242+
- [Azure Managed HSM overview](overview.md)
243+
- [Azure Managed HSM local RBAC built-in roles](built-in-roles.md)
244+
- [Azure Managed HSM role management](role-management.md)

‎articles/key-vault/managed-hsm/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,8 @@ items:
7171
items:
7272
- name: Secure key release policy grammar
7373
href: policy-grammar.md
74+
- name: TLS offload library
75+
href: tls-offload-library.md
7476
- name: Key management in Azure
7577
href: ../../security/fundamentals/key-management.md
7678
- name: Azure PowerShell

0 commit comments

Comments
 (0)