0
# Managed HSM Operations
1

2
Complete lifecycle management for Azure Managed Hardware Security Module (HSM) instances, providing dedicated HSM resources with enhanced security, compliance capabilities, and hardware-backed cryptographic operations. Managed HSMs offer FIPS 140-2 Level 3 validated security for high-value cryptographic workloads.
3

4
## Capabilities
5

6
### HSM Creation and Updates
7

8
Create new Managed HSM instances or update existing configurations with support for long-running operations, geo-replication, and advanced security settings.
9

10
```python { .api }
11
def begin_create_or_update(
12
    resource_group_name: str,
13
    name: str,
14
    parameters: ManagedHsm
15
) -> LROPoller[ManagedHsm]:
16
    """
17
    Create or update a managed HSM Pool in the specified subscription.
18
    
19
    Args:
20
        resource_group_name (str): Name of the resource group
21
        name (str): Name of the managed HSM Pool
22
        parameters (ManagedHsm): Parameters to create or update the managed HSM
23
        
24
    Returns:
25
        LROPoller[ManagedHsm]: Long-running operation poller for HSM creation/update
26
    """
27

28
def begin_update(
29
    resource_group_name: str,
30
    name: str,
31
    parameters: ManagedHsm
32
) -> LROPoller[ManagedHsm]:
33
    """
34
    Update a managed HSM Pool in the specified subscription.
35
    
36
    Args:
37
        resource_group_name (str): Name of the resource group
38
        name (str): Name of the managed HSM Pool
39
        parameters (ManagedHsm): Parameters to update the managed HSM
40
        
41
    Returns:
42
        LROPoller[ManagedHsm]: Long-running operation poller for HSM update
43
    """
44
```
45

46
### HSM Retrieval and Listing
47

48
Retrieve individual Managed HSM instances or list HSMs within resource groups or subscriptions.
49

50
```python { .api }
51
def get(resource_group_name: str, name: str) -> Optional[ManagedHsm]:
52
    """
53
    Get the specified managed HSM Pool.
54
    
55
    Args:
56
        resource_group_name (str): Name of the resource group
57
        name (str): Name of the managed HSM Pool
58
        
59
    Returns:
60
        Optional[ManagedHsm]: The managed HSM resource, or None if not found
61
    """
62

63
def list_by_resource_group(
64
    resource_group_name: str,
65
    top: Optional[int] = None
66
) -> ItemPaged[ManagedHsm]:
67
    """
68
    List managed HSM Pools within a resource group.
69
    
70
    Args:
71
        resource_group_name (str): Name of the resource group
72
        top (int, optional): Maximum number of results to return
73
        
74
    Returns:
75
        ItemPaged[ManagedHsm]: Paginated list of managed HSMs
76
    """
77

78
def list_by_subscription(top: Optional[int] = None) -> ItemPaged[ManagedHsm]:
79
    """
80
    List managed HSM Pools associated with the subscription.
81
    
82
    Args:
83
        top (int, optional): Maximum number of results to return
84
        
85
    Returns:
86
        ItemPaged[ManagedHsm]: Paginated list of managed HSMs
87
    """
88
```
89

90
### HSM Deletion and Recovery
91

92
Delete Managed HSM instances with soft delete support, and permanently purge when needed.
93

94
```python { .api }
95
def begin_delete(resource_group_name: str, name: str) -> LROPoller[None]:
96
    """
97
    Delete the specified managed HSM Pool.
98
    
99
    Args:
100
        resource_group_name (str): Name of the resource group
101
        name (str): Name of the managed HSM Pool
102
        
103
    Returns:
104
        LROPoller[None]: Long-running operation poller for HSM deletion
105
    """
106

107
def list_deleted() -> ItemPaged[DeletedManagedHsm]:
108
    """
109
    Get information about deleted managed HSMs in a subscription.
110
    
111
    Returns:
112
        ItemPaged[DeletedManagedHsm]: Paginated list of deleted HSMs
113
    """
114

115
def get_deleted(name: str, location: str) -> DeletedManagedHsm:
116
    """
117
    Get the specified deleted managed HSM.
118
    
119
    Args:
120
        name (str): The name of the deleted managed HSM
121
        location (str): The location of the deleted managed HSM
122
        
123
    Returns:
124
        DeletedManagedHsm: The deleted managed HSM information
125
    """
126

127
def begin_purge_deleted(name: str, location: str) -> LROPoller[None]:
128
    """
129
    Permanently delete the specified managed HSM. This action cannot be undone.
130
    
131
    Args:
132
        name (str): The name of the deleted managed HSM
133
        location (str): The location of the deleted managed HSM
134
        
135
    Returns:
136
        LROPoller[None]: Long-running operation poller for HSM purge
137
    """
138
```
139

140
### HSM Key Management
141

142
Manage cryptographic keys within Managed HSM instances with hardware-backed security.
143

144
```python { .api }
145
def create_if_not_exist(
146
    resource_group_name: str,
147
    name: str,
148
    key_name: str,
149
    parameters: ManagedHsmKeyCreateParameters
150
) -> ManagedHsmKey:
151
    """
152
    Create the first version of a new key if it does not exist in the HSM.
153
    
154
    Args:
155
        resource_group_name (str): Name of the resource group
156
        name (str): Name of the managed HSM
157
        key_name (str): The name of the key to create
158
        parameters (ManagedHsmKeyCreateParameters): Parameters to create the key
159
        
160
    Returns:
161
        ManagedHsmKey: The created HSM key
162
    """
163

164
def get(resource_group_name: str, name: str, key_name: str) -> ManagedHsmKey:
165
    """
166
    Get the current version of the specified key from the HSM.
167
    
168
    Args:
169
        resource_group_name (str): Name of the resource group
170
        name (str): Name of the managed HSM
171
        key_name (str): The name of the key to retrieve
172
        
173
    Returns:
174
        ManagedHsmKey: The HSM key resource
175
    """
176

177
def list(resource_group_name: str, name: str) -> ItemPaged[ManagedHsmKey]:
178
    """
179
    List keys in the specified managed HSM.
180
    
181
    Args:
182
        resource_group_name (str): Name of the resource group
183
        name (str): Name of the managed HSM
184
        
185
    Returns:
186
        ItemPaged[ManagedHsmKey]: Paginated list of HSM keys
187
    """
188
```
189

190
### HSM Region Management
191

192
List and manage geo-replication regions for Managed HSM instances, providing information about regional availability and replication status.
193

194
```python { .api }
195
def list_by_resource(resource_group_name: str, name: str) -> ItemPaged[MHSMGeoReplicatedRegion]:
196
    """
197
    List regions associated with the managed HSM Pool.
198
    
199
    Args:
200
        resource_group_name (str): The name of the Resource Group
201
        name (str): The name of the managed HSM Pool
202
        
203
    Returns:
204
        ItemPaged[MHSMGeoReplicatedRegion]: List of regions for the HSM
205
    """
206
```
207

208
### Name Availability
209

210
Check availability of Managed HSM names before creation.
211

212
```python { .api }
213
def check_mhsm_name_availability(
214
    mhsm_name: CheckMhsmNameAvailabilityParameters
215
) -> CheckMhsmNameAvailabilityResult:
216
    """
217
    Check that the managed HSM name is valid and not already in use.
218
    
219
    Args:
220
        mhsm_name (CheckMhsmNameAvailabilityParameters): The name to check
221
        
222
    Returns:
223
        CheckMhsmNameAvailabilityResult: The name availability result
224
    """
225
```
226

227
## Usage Examples
228

229
### Creating a Managed HSM
230

231
```python
232
from azure.mgmt.keyvault import KeyVaultManagementClient
233
from azure.mgmt.keyvault.models import (
234
    ManagedHsm, ManagedHsmProperties, ManagedHsmSku, ManagedHsmSkuName,
235
    ManagedServiceIdentity, ManagedServiceIdentityType,
236
    MHSMNetworkRuleSet, NetworkRuleAction
237
)
238
from azure.identity import DefaultAzureCredential
239

240
credential = DefaultAzureCredential()
241
client = KeyVaultManagementClient(credential, "subscription-id")
242

243
# Create Managed HSM
244
hsm_properties = ManagedHsmProperties(
245
    tenant_id="tenant-id",
246
    initial_admin_object_ids=["admin-object-id-1", "admin-object-id-2"],
247
    enable_soft_delete=True,
248
    soft_delete_retention_in_days=90,
249
    enable_purge_protection=True,
250
    network_acls=MHSMNetworkRuleSet(
251
        default_action=NetworkRuleAction.DENY,
252
        bypass="AzureServices"
253
    )
254
)
255

256
managed_hsm = ManagedHsm(
257
    location="East US",
258
    sku=ManagedHsmSku(
259
        family="B",
260
        name=ManagedHsmSkuName.STANDARD_B1
261
    ),
262
    identity=ManagedServiceIdentity(
263
        type=ManagedServiceIdentityType.SYSTEM_ASSIGNED
264
    ),
265
    properties=hsm_properties,
266
    tags={"environment": "production", "purpose": "key-management"}
267
)
268

269
# Start HSM creation (long-running operation)
270
poller = client.managed_hsms.begin_create_or_update(
271
    "my-resource-group",
272
    "my-managed-hsm",
273
    managed_hsm
274
)
275

276
hsm = poller.result()
277
print(f"Created Managed HSM: {hsm.name}")
278
print(f"HSM URI: {hsm.properties.hsm_uri}")
279
```
280

281
### Managing HSM Keys
282

283
```python
284
from azure.mgmt.keyvault.models import (
285
    ManagedHsmKeyCreateParameters, ManagedHsmKeyProperties,
286
    JsonWebKeyType, JsonWebKeyOperation
287
)
288

289
# Create HSM-backed key
290
key_params = ManagedHsmKeyCreateParameters(
291
    properties=ManagedHsmKeyProperties(
292
        kty=JsonWebKeyType.RSA_HSM,
293
        key_size=3072,
294
        key_ops=[
295
            JsonWebKeyOperation.ENCRYPT,
296
            JsonWebKeyOperation.DECRYPT,
297
            JsonWebKeyOperation.SIGN,
298
            JsonWebKeyOperation.VERIFY
299
        ]
300
    )
301
)
302

303
hsm_key = client.managed_hsm_keys.create_if_not_exist(
304
    "my-resource-group",
305
    "my-managed-hsm",
306
    "my-hsm-key",
307
    key_params
308
)
309
print(f"Created HSM key: {hsm_key.name}")
310

311
# List all keys in HSM
312
for key in client.managed_hsm_keys.list("my-resource-group", "my-managed-hsm"):
313
    print(f"HSM Key: {key.name}, Type: {key.properties.kty}")
314
```
315

316
### Managing Deleted HSMs
317

318
```python
319
# List deleted HSMs
320
for deleted_hsm in client.managed_hsms.list_deleted():
321
    print(f"Deleted HSM: {deleted_hsm.name}")
322
    print(f"Deletion date: {deleted_hsm.properties.deletion_date}")
323

324
# Permanently purge deleted HSM
325
purge_poller = client.managed_hsms.begin_purge_deleted("my-hsm", "East US")
326
purge_poller.wait()
327
print("HSM permanently purged")
328
```
329

330
### Managing HSM Geo-Replication
331

332
```python
333
# Check geo-replication status for Managed HSM
334
for region in client.mhsm_regions.list_by_resource("my-resource-group", "my-managed-hsm"):
335
    print(f"Region: {region.name}")
336
    print(f"Provisioning State: {region.provisioning_state}")
337
    print(f"Is Primary: {region.is_primary}")
338
    if region.is_primary:
339
        print("  This is the primary region")
340
    else:
341
        print("  This is a replica region")
342
    print()
343
```
344

345
## Types
346

347
### Managed HSM Resource
348

349
```python { .api }
350
class ManagedHsm:
351
    id: Optional[str]
352
    name: Optional[str]
353
    type: Optional[str]
354
    location: Optional[str]
355
    sku: Optional[ManagedHsmSku]
356
    tags: Optional[Dict[str, str]]
357
    identity: Optional[ManagedServiceIdentity]
358
    properties: Optional[ManagedHsmProperties]
359
    system_data: Optional[SystemData]
360
```
361

362
### HSM Properties
363

364
```python { .api }
365
class ManagedHsmProperties:
366
    tenant_id: Optional[str]
367
    initial_admin_object_ids: Optional[List[str]]
368
    hsm_uri: Optional[str]
369
    enable_soft_delete: Optional[bool]
370
    soft_delete_retention_in_days: Optional[int]
371
    enable_purge_protection: Optional[bool]
372
    create_mode: Optional[CreateMode]
373
    status_message: Optional[str]
374
    provisioning_state: Optional[ProvisioningState]
375
    network_acls: Optional[MHSMNetworkRuleSet]
376
    regions: Optional[List[MHSMGeoReplicatedRegion]]
377
    private_endpoint_connections: Optional[List[MHSMPrivateEndpointConnectionItem]]
378
    public_network_access: Optional[PublicNetworkAccess]
379
    scheduled_purge_date: Optional[datetime]
380
    security_domain_properties: Optional[ManagedHSMSecurityDomainProperties]
381
```
382

383
### HSM SKU
384

385
```python { .api }
386
class ManagedHsmSku:
387
    family: ManagedHsmSkuFamily
388
    name: ManagedHsmSkuName
389

390
class ManagedHsmSkuName(str, Enum):
391
    STANDARD_B1 = "Standard_B1"
392
    CUSTOM_B32 = "Custom_B32"
393
    CUSTOM_B6 = "Custom_B6"
394

395
class ManagedHsmSkuFamily(str, Enum):
396
    B = "B"
397
```
398

399
### HSM Keys
400

401
```python { .api }
402
class ManagedHsmKey:
403
    id: Optional[str]
404
    name: Optional[str]
405
    type: Optional[str]
406
    location: Optional[str]
407
    tags: Optional[Dict[str, str]]
408
    properties: Optional[ManagedHsmKeyProperties]
409

410
class ManagedHsmKeyProperties:
411
    attributes: Optional[ManagedHsmKeyAttributes]
412
    kty: Optional[JsonWebKeyType]
413
    key_ops: Optional[List[JsonWebKeyOperation]]
414
    key_size: Optional[int]
415
    curve: Optional[JsonWebKeyCurveName]
416
    key_uri: Optional[str]
417
    key_uri_with_version: Optional[str]
418
    version: Optional[str]
419
    release_policy: Optional[ManagedHsmKeyReleasePolicy]
420
    rotation_policy: Optional[ManagedHsmRotationPolicy]
421
```
422

423
### Network Security
424

425
```python { .api }
426
class MHSMNetworkRuleSet:
427
    bypass: Optional[str]
428
    default_action: Optional[NetworkRuleAction]
429
    ip_rules: Optional[List[MHSMIPRule]]
430
    virtual_network_rules: Optional[List[MHSMVirtualNetworkRule]]
431

432
class MHSMIPRule:
433
    value: str
434

435
class MHSMVirtualNetworkRule:
436
    id: str
437
```
438

439
### Deleted HSM
440

441
```python { .api }
442
class DeletedManagedHsm:
443
    id: Optional[str]
444
    name: Optional[str]
445
    type: Optional[str]
446
    properties: Optional[DeletedManagedHsmProperties]
447

448
class DeletedManagedHsmProperties:
449
    mhsm_id: Optional[str]
450
    location: Optional[str]
451
    deletion_date: Optional[datetime]
452
    scheduled_purge_date: Optional[datetime]
453
    purge_protection_enabled: Optional[bool]
454
    tags: Optional[Dict[str, str]]
455
```
456

457
### Geo-Replication Regions
458

459
```python { .api }
460
class MHSMGeoReplicatedRegion:
461
    name: Optional[str]
462
    provisioning_state: Optional[GeoReplicationRegionProvisioningState]
463
    is_primary: Optional[bool]
464

465
class GeoReplicationRegionProvisioningState(str, Enum):
466
    PROVISIONING = "Provisioning"
467
    SUCCEEDED = "Succeeded"
468
    DELETING = "Deleting"
469
    FAILED = "Failed"
470
    CLEANUP = "Cleanup"
471
```
472

473
### Name Availability
474

475
```python { .api }
476
class CheckMhsmNameAvailabilityParameters:
477
    name: str
478

479
class CheckMhsmNameAvailabilityResult:
480
    name_available: Optional[bool]
481
    reason: Optional[Reason]
482
    message: Optional[str]
483
```
484

485
## Security and Compliance Features
486

487
### FIPS 140-2 Level 3 Compliance
488

489
Managed HSMs provide hardware-backed cryptographic operations with FIPS 140-2 Level 3 validated security modules, ensuring the highest level of cryptographic protection for sensitive workloads.
490

491
### Multi-Admin Control
492

493
Initial admin object IDs enable multi-person control for HSM administration, supporting security policies that require multiple administrators for sensitive operations.
494

495
### Geo-Replication
496

497
Managed HSMs support geo-replication for high availability and disaster recovery, with configurable regions for key backup and recovery scenarios.