0
# Key Management
1

2
Comprehensive key lifecycle management for cryptographic keys in Azure Key Vault. Supports RSA, Elliptic Curve (EC), and symmetric keys with Hardware Security Module (HSM) backing. Provides key creation, versioning, rotation, backup/restore, and soft-delete recovery capabilities.
3

4
```python
5
# Required imports for long-running operations
6
from azure.core.polling import LROPoller
7
```
8

9
## Capabilities
10

11
### Key Client
12

13
Main client for key management operations supporting both synchronous and asynchronous usage patterns.
14

15
```python { .api }
16
class KeyClient:
17
    def __init__(self, vault_url: str, credential, **kwargs):
18
        """
19
        Initialize KeyClient for key management operations.
20
        
21
        Parameters:
22
        - vault_url: str, Key Vault URL (https://vault-name.vault.azure.net/)
23
        - credential: Azure credential object for authentication
24
        - api_version: ApiVersion, API version to use (default: latest)
25
        - **kwargs: Additional configuration options
26
        """
27

28
    def close(self) -> None:
29
        """Close the client and release resources."""
30
```
31

32
### Key Creation
33

34
Create new cryptographic keys with various algorithms and parameters.
35

36
```python { .api }
37
def create_key(self, name: str, key_type: KeyType, **kwargs) -> KeyVaultKey:
38
    """
39
    Create a new key in the Key Vault.
40
    
41
    Parameters:
42
    - name: str, unique key name within the vault
43
    - key_type: KeyType, type of key to create (rsa, ec, oct, etc.)
44
    - size: int, key size in bits (RSA: 2048, 3072, 4096; EC: 256, 384, 521)
45
    - curve: KeyCurveName, curve for EC keys (p_256, p_384, p_521, p_256k)  
46
    - key_operations: List[KeyOperation], allowed operations
47
    - enabled: bool, whether key is enabled for use
48
    - expires_on: datetime, expiration date
49
    - not_before: datetime, activation date
50
    - tags: Dict[str, str], custom metadata
51
    - hsm: bool, create HSM-backed key
52
    
53
    Returns:
54
    KeyVaultKey with key metadata and public key material
55
    """
56

57
def create_rsa_key(self, name: str, **kwargs) -> KeyVaultKey:
58
    """
59
    Create RSA key with specified size.
60
    
61
    Parameters:
62
    - name: str, unique key name
63
    - size: int, key size (2048, 3072, 4096)
64
    - hardware_protected: bool, use HSM backing
65
    - **kwargs: Additional key properties
66
    
67
    Returns:
68
    KeyVaultKey with RSA key
69
    """
70

71
def create_ec_key(self, name: str, **kwargs) -> KeyVaultKey:
72
    """
73
    Create Elliptic Curve key.
74
    
75
    Parameters:
76
    - name: str, unique key name  
77
    - curve: KeyCurveName, EC curve to use
78
    - hardware_protected: bool, use HSM backing
79
    - **kwargs: Additional key properties
80
    
81
    Returns:
82
    KeyVaultKey with EC key
83
    """
84

85
def create_oct_key(self, name: str, **kwargs) -> KeyVaultKey:
86
    """
87
    Create symmetric key for AES operations.
88
    
89
    Parameters:
90
    - name: str, unique key name
91
    - size: int, key size in bits (128, 192, 256)
92
    - hardware_protected: bool, use HSM backing  
93
    - **kwargs: Additional key properties
94
    
95
    Returns:
96
    KeyVaultKey with symmetric key
97
    """
98

99
def import_key(self, name: str, key: JsonWebKey, **kwargs) -> KeyVaultKey:
100
    """
101
    Import existing key material.
102
    
103
    Parameters:
104
    - name: str, unique key name
105
    - key: JsonWebKey, key material to import
106
    - hsm: bool, import to HSM
107
    - **kwargs: Additional key properties
108
    
109
    Returns:
110
    KeyVaultKey with imported key
111
    """
112
```
113

114
### Key Retrieval
115

116
Retrieve keys and their versions from the vault.
117

118
```python { .api }
119
def get_key(self, name: str, version: str = None, **kwargs) -> KeyVaultKey:
120
    """
121
    Get a key from the vault.
122
    
123
    Parameters:
124
    - name: str, key name
125
    - version: str, specific version (default: latest)
126
    
127
    Returns:
128
    KeyVaultKey with key data and metadata
129
    """
130

131
def list_properties_of_keys(**kwargs) -> ItemPaged[KeyProperties]:
132
    """
133
    List all keys in the vault.
134
    
135
    Parameters:
136
    - max_page_size: int, maximum items per page
137
    
138
    Returns:
139
    Paginated list of KeyProperties
140
    """
141

142
def list_properties_of_key_versions(self, name: str, **kwargs) -> ItemPaged[KeyProperties]:
143
    """
144
    List all versions of a specific key.
145
    
146
    Parameters:
147
    - name: str, key name
148
    - max_page_size: int, maximum items per page
149
    
150
    Returns:
151
    Paginated list of KeyProperties for all versions
152
    """
153
```
154

155
### Key Operations
156

157
Update, delete, and manage key lifecycle.
158

159
```python { .api }
160
def update_key_properties(self, name: str, version: str = None, **kwargs) -> KeyVaultKey:
161
    """
162
    Update key properties and metadata.
163
    
164
    Parameters:
165
    - name: str, key name
166
    - version: str, specific version (default: latest)
167
    - key_operations: List[KeyOperation], allowed operations
168
    - enabled: bool, enable/disable key
169
    - expires_on: datetime, expiration date
170
    - not_before: datetime, activation date
171
    - tags: Dict[str, str], custom metadata
172
    
173
    Returns:
174
    KeyVaultKey with updated properties
175
    """
176

177
def begin_delete_key(self, name: str, **kwargs) -> LROPoller[DeletedKey]:
178
    """
179
    Delete a key (soft delete) - long-running operation.
180
    
181
    Parameters:
182
    - name: str, key name to delete
183
    
184
    Returns:
185
    LROPoller[DeletedKey] for tracking deletion progress
186
    """
187

188
def get_deleted_key(self, name: str, **kwargs) -> DeletedKey:
189
    """
190
    Get properties of a deleted key.
191
    
192
    Parameters:
193
    - name: str, deleted key name
194
    
195
    Returns:
196
    DeletedKey with deletion information
197
    """
198

199
def begin_recover_deleted_key(self, name: str, **kwargs) -> LROPoller[KeyVaultKey]:
200
    """
201
    Recover a deleted key - long-running operation.
202
    
203
    Parameters:
204
    - name: str, deleted key name
205
    
206
    Returns:
207
    LROPoller[KeyVaultKey] for tracking recovery progress
208
    """
209

210
def purge_deleted_key(self, name: str, **kwargs) -> None:
211
    """
212
    Permanently delete a key.
213
    
214
    Parameters:
215
    - name: str, deleted key name to purge
216
    """
217

218
def list_deleted_keys(**kwargs) -> ItemPaged[DeletedKey]:
219
    """
220
    List all deleted keys.
221
    
222
    Returns:
223
    Paginated list of DeletedKey objects
224
    """
225
```
226

227
### Key Backup and Restore
228

229
Backup and restore keys for disaster recovery.
230

231
```python { .api }
232
def backup_key(self, name: str, **kwargs) -> bytes:
233
    """
234
    Create backup of a key.
235
    
236
    Parameters:
237
    - name: str, key name to backup
238
    
239
    Returns:
240
    bytes containing encrypted backup data
241
    """
242

243
def restore_key_backup(self, backup: bytes, **kwargs) -> KeyVaultKey:
244
    """
245
    Restore key from backup.
246
    
247
    Parameters:
248
    - backup: bytes, backup data from backup_key()
249
    
250
    Returns:
251
    KeyVaultKey with restored key
252
    """
253
```
254

255
### Key Rotation
256

257
Manage key rotation policies and operations.
258

259
```python { .api }
260
def rotate_key(self, name: str, **kwargs) -> KeyVaultKey:
261
    """
262
    Create new version of existing key.
263
    
264
    Parameters:
265
    - name: str, key name to rotate
266
    
267
    Returns:
268
    KeyVaultKey with new version
269
    """
270

271
def get_key_rotation_policy(self, name: str, **kwargs) -> KeyRotationPolicy:
272
    """
273
    Get rotation policy for a key.
274
    
275
    Parameters:
276
    - name: str, key name
277
    
278
    Returns:
279
    KeyRotationPolicy with policy details
280
    """
281

282
def update_key_rotation_policy(self, name: str, policy: KeyRotationPolicy, **kwargs) -> KeyRotationPolicy:
283
    """
284
    Update key rotation policy.
285
    
286
    Parameters:
287
    - name: str, key name
288
    - policy: KeyRotationPolicy, new policy configuration
289
    
290
    Returns:
291
    KeyRotationPolicy with updated policy
292
    """
293
```
294

295
### Advanced Operations
296

297
Additional key management capabilities.
298

299
```python { .api }
300
def get_random_bytes(self, count: int, **kwargs) -> bytes:
301
    """
302
    Generate cryptographically secure random bytes.
303
    
304
    Parameters:
305
    - count: int, number of random bytes (1-128)
306
    
307
    Returns:
308
    bytes containing random data
309
    """
310

311
def release_key(self, name: str, target_attestation_token: str, **kwargs) -> ReleaseKeyResult:
312
    """
313
    Release key to authorized environment.
314
    
315
    Parameters:
316
    - name: str, key name
317
    - target_attestation_token: str, attestation token for target environment
318
    - version: str, key version
319
    - algorithm: KeyExportEncryptionAlgorithm, encryption algorithm
320
    
321
    Returns:
322
    ReleaseKeyResult with released key data
323
    """
324

325
def get_cryptography_client(self, key_name: str, **kwargs) -> CryptographyClient:
326
    """
327
    Get CryptographyClient for key operations.
328
    
329
    Parameters:
330
    - key_name: str, key to use for crypto operations
331
    - key_version: str, specific key version
332
    
333
    Returns:
334
    CryptographyClient configured for the key
335
    """
336
```
337

338
## Key Types and Enumerations
339

340
```python { .api }
341
class KeyType(str, Enum):
342
    """Supported key types."""
343
    rsa = "RSA"
344
    rsa_hsm = "RSA-HSM"
345
    ec = "EC"
346
    ec_hsm = "EC-HSM"  
347
    oct = "oct"
348
    oct_hsm = "oct-HSM"
349

350
class KeyCurveName(str, Enum):
351
    """Elliptic curve names."""
352
    p_256 = "P-256"
353
    p_384 = "P-384"
354
    p_521 = "P-521"
355
    p_256k = "P-256K"
356

357
class KeyOperation(str, Enum):
358
    """Allowed key operations."""
359
    encrypt = "encrypt"
360
    decrypt = "decrypt"
361
    sign = "sign"
362
    verify = "verify"
363
    wrap_key = "wrapKey"
364
    unwrap_key = "unwrapKey"
365
    import_key = "import"
366
    export = "export"
367

368
class KeyRotationPolicyAction(str, Enum):
369
    """Key rotation policy actions."""
370
    rotate = "rotate"
371
    notify = "notify"
372

373
class KeyExportEncryptionAlgorithm(str, Enum):
374
    """Encryption algorithms for key export."""
375
    ckm_rsa_aes_key_wrap = "CKM_RSA_AES_KEY_WRAP"
376
    rsa_aes_key_wrap_256 = "RSA_AES_KEY_WRAP_256"
377
    rsa_aes_key_wrap_384 = "RSA_AES_KEY_WRAP_384"
378
```
379

380
## Key Model Classes
381

382
```python { .api }
383
class KeyVaultKey:
384
    """Represents a key stored in Azure Key Vault."""
385
    id: str
386
    name: str
387
    properties: KeyProperties
388
    key: JsonWebKey
389
    key_type: KeyType
390

391
class JsonWebKey:
392
    """JSON Web Key representation of key material."""
393
    kid: str  # Key identifier
394
    kty: str  # Key type
395
    key_ops: List[str]  # Key operations
396
    n: bytes  # RSA modulus
397
    e: bytes  # RSA public exponent
398
    d: bytes  # RSA private exponent (for local keys)
399
    p: bytes  # RSA first prime factor
400
    q: bytes  # RSA second prime factor
401
    x: bytes  # EC x coordinate
402
    y: bytes  # EC y coordinate
403
    k: bytes  # Symmetric key value
404
    crv: str  # EC curve name
405

406
class KeyProperties:
407
    """Key metadata and properties."""
408
    id: str
409
    name: str
410
    version: str
411
    enabled: bool
412
    expires_on: datetime
413
    not_before: datetime
414
    created_on: datetime
415
    updated_on: datetime
416
    recovery_level: str
417
    vault_url: str
418
    tags: Dict[str, str]
419

420
class DeletedKey:
421
    """Represents a deleted key."""
422
    id: str
423
    name: str
424
    properties: KeyProperties
425
    key: JsonWebKey
426
    deleted_on: datetime
427
    recovery_id: str
428
    scheduled_purge_date: datetime
429

430
class KeyVaultKeyIdentifier:
431
    """Identifier for Key Vault keys."""
432
    source_id: str
433
    vault_url: str
434
    name: str
435
    version: str
436

437
class KeyRotationPolicy:
438
    """Key rotation policy configuration."""
439
    id: str
440
    lifetime_actions: List[KeyRotationLifetimeAction]
441
    expires_in: str  # ISO 8601 duration
442
    created_on: datetime
443
    updated_on: datetime
444

445
class KeyRotationLifetimeAction:
446
    """Lifetime actions for key rotation."""
447
    action: KeyRotationPolicyAction
448
    time_after_create: str  # ISO 8601 duration
449
    time_before_expiry: str  # ISO 8601 duration
450

451
class KeyReleasePolicy:
452
    """Key release policy."""
453
    encoded_policy: str
454
    content_type: str
455

456
class ReleaseKeyResult:
457
    """Result of key release operation."""
458
    value: str
459
```
460

461
## Usage Examples
462

463
### Basic Key Management
464

465
```python
466
from azure.keyvault.keys import KeyClient
467
from azure.identity import DefaultAzureCredential
468

469
# Initialize client
470
credential = DefaultAzureCredential()
471
client = KeyClient(vault_url="https://vault-name.vault.azure.net/", credential=credential)
472

473
# Create RSA key
474
rsa_key = client.create_rsa_key("my-rsa-key", size=2048)
475
print(f"Created key: {rsa_key.name} (ID: {rsa_key.id})")
476

477
# Create EC key  
478
ec_key = client.create_ec_key("my-ec-key", curve=KeyCurveName.p_256)
479

480
# Get key
481
retrieved_key = client.get_key("my-rsa-key")
482
print(f"Key enabled: {retrieved_key.properties.enabled}")
483

484
# List all keys
485
for key_properties in client.list_properties_of_keys():
486
    print(f"Key: {key_properties.name}")
487
```
488

489
### Key Rotation
490

491
```python
492
from azure.keyvault.keys import KeyRotationPolicy, KeyRotationLifetimeAction
493

494
# Create rotation policy
495
lifetime_action = KeyRotationLifetimeAction(
496
    action=KeyRotationPolicyAction.rotate,
497
    time_before_expiry="P30D"  # 30 days before expiry
498
)
499

500
policy = KeyRotationPolicy(
501
    expires_in="P1Y",  # 1 year
502
    lifetime_actions=[lifetime_action]
503
)
504

505
# Set rotation policy
506
client.update_key_rotation_policy("my-key", policy)
507

508
# Manual rotation
509
rotated_key = client.rotate_key("my-key")
510
```
511

512
### Backup and Recovery
513

514
```python
515
# Backup key
516
backup_data = client.backup_key("important-key")
517

518
# Simulate deletion
519
delete_poller = client.begin_delete_key("important-key")
520
deleted_key = delete_poller.result()  # Wait for completion
521

522
# Restore from backup
523
restored_key = client.restore_key_backup(backup_data)
524

525
# Or recover deleted key
526
recover_poller = client.begin_recover_deleted_key("important-key")
527
recovered_key = recover_poller.result()  # Wait for completion
528
```