Skip to content

Commit bd017d5

Browse files
author
Nicola Camillucci
committed
Added samples
1 parent ef3f662 commit bd017d5

2 files changed

Lines changed: 158 additions & 0 deletions

File tree

‎sdk/keyvault/azure-keyvault-keys/samples/external_key_operations.py‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# pylint: disable=line-too-long,useless-suppression
2+
# ------------------------------------
3+
# Copyright (c) Microsoft Corporation.
4+
# Licensed under the MIT License.
5+
# ------------------------------------
6+
import os
7+
8+
from azure.identity import DefaultAzureCredential
9+
from azure.keyvault.keys import ExternalKey, KeyClient
10+
11+
# ----------------------------------------------------------------------------------------------------------
12+
# Prerequisites:
13+
# 1. An Azure Key Vault Managed HSM (https://learn.microsoft.com/azure/key-vault/managed-hsm/quick-create-cli)
14+
#
15+
# 2. azure-keyvault-keys and azure-identity libraries (pip install these)
16+
#
17+
# 3. Set environment variable MANAGED_HSM_URL with the URL of your Managed HSM
18+
#
19+
# 4. Set up your environment to use azure-identity's DefaultAzureCredential. For more information about how to configure
20+
# the DefaultAzureCredential, refer to https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential
21+
#
22+
# 5. Key create, get, and delete permissions for your service principal in your Managed HSM
23+
#
24+
# 6. The Managed HSM is configured with an external HSM source that owns the key material referenced by external_key.id
25+
#
26+
# ----------------------------------------------------------------------------------------------------------
27+
# Sample - demonstrates External Key Management (EKM) operations against a Managed HSM that is backed by an
28+
# external HSM. The external HSM owns the key material; Managed HSM stores a reference (`ExternalKey.id`) to
29+
# that key.
30+
#
31+
# Note: External Key Management requires API version 2026-01-01-preview or later and is only supported on
32+
# Managed HSM (not regular Key Vault).
33+
#
34+
# 1. Register a key whose material is owned by an external HSM (create_external_key)
35+
#
36+
# 2. Retrieve the key and inspect the external_key reference (get_key)
37+
#
38+
# 3. Delete the key registration (begin_delete_key)
39+
#
40+
# 4. Purge the key registration (purge_deleted_key)
41+
# ----------------------------------------------------------------------------------------------------------
42+
43+
# Instantiate a key client that will be used to call the service.
44+
# Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
45+
MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
46+
credential = DefaultAzureCredential()
47+
client = KeyClient(vault_url=MANAGED_HSM_URL, credential=credential)
48+
49+
# Build an ExternalKey that references the key material managed in the external HSM.
50+
# The id must be at most 64 characters and may only contain letters, digits, and hyphens.
51+
print("\n.. Create an External Key")
52+
key_name = "externalKeyName"
53+
external_key = ExternalKey(id="external-key-reference-id")
54+
key = client.create_external_key(key_name, external_key=external_key)
55+
print(f"External key '{key.name}' was registered with external id '{key.properties.external_key.id}'.")
56+
print(f"Key type is '{key.key_type}' and key size is '{key.properties.key_size}'.")
57+
58+
# Read the registration back to confirm the external_key reference is round-tripped.
59+
print("\n.. Get the External Key by name")
60+
fetched = client.get_key(key.name)
61+
print(f"Key with name '{fetched.name}' has external_key id '{fetched.properties.external_key.id}'.")
62+
print(f"Key type is '{fetched.key_type}' and key size is '{fetched.properties.key_size}'.")
63+
64+
# The external key registration is no longer used; delete it from the Managed HSM.
65+
# Deleting the registration does not delete the key material in the external HSM.
66+
print("\n.. Delete the External Key")
67+
client.begin_delete_key(key.name).wait()
68+
print(f"Deleted external key '{key.name}'.")
69+
70+
# The deleted key registration still exists in the Managed HSM's soft-deleted state. Purge it to remove it permanently.
71+
print("\n.. Purge the deleted External Key")
72+
client.purge_deleted_key(key.name)
73+
print(f"Purged external key '{key.name}'.")

‎sdk/keyvault/azure-keyvault-keys/samples/external_key_operations_async.py‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# pylint: disable=line-too-long,useless-suppression
2+
# ------------------------------------
3+
# Copyright (c) Microsoft Corporation.
4+
# Licensed under the MIT License.
5+
# ------------------------------------
6+
import asyncio
7+
import os
8+
9+
from azure.identity.aio import DefaultAzureCredential
10+
from azure.keyvault.keys import ExternalKey
11+
from azure.keyvault.keys.aio import KeyClient
12+
13+
# ----------------------------------------------------------------------------------------------------------
14+
# Prerequisites:
15+
# 1. An Azure Key Vault Managed HSM (https://learn.microsoft.com/azure/key-vault/managed-hsm/quick-create-cli)
16+
#
17+
# 2. azure-keyvault-keys and azure-identity libraries (pip install these)
18+
#
19+
# 3. Set environment variable MANAGED_HSM_URL with the URL of your Managed HSM
20+
#
21+
# 4. Set up your environment to use azure-identity's DefaultAzureCredential. For more information about how to configure
22+
# the DefaultAzureCredential, refer to https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential
23+
#
24+
# 5. Key create, get, and delete permissions for your service principal in your Managed HSM
25+
#
26+
# 6. The Managed HSM is configured with an external HSM source that owns the key material referenced by external_key.id
27+
#
28+
# ----------------------------------------------------------------------------------------------------------
29+
# Sample - demonstrates External Key Management (EKM) operations against a Managed HSM that is backed by an
30+
# external HSM. The external HSM owns the key material; Managed HSM stores a reference (`ExternalKey.id`) to
31+
# that key.
32+
#
33+
# Note: External Key Management requires API version 2026-01-01-preview or later and is only supported on
34+
# Managed HSM (not regular Key Vault).
35+
#
36+
# 1. Register a key whose material is owned by an external HSM (create_external_key)
37+
#
38+
# 2. Retrieve the key and inspect the external_key reference (get_key)
39+
#
40+
# 3. Delete the key registration (begin_delete_key)
41+
#
42+
# 4. Purge the key registration (purge_deleted_key)
43+
# ----------------------------------------------------------------------------------------------------------
44+
45+
46+
async def run_sample():
47+
# Instantiate a key client that will be used to call the service.
48+
# Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
49+
MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
50+
credential = DefaultAzureCredential()
51+
client = KeyClient(vault_url=MANAGED_HSM_URL, credential=credential)
52+
53+
# Build an ExternalKey that references the key material managed in the external HSM.
54+
# The id must be at most 64 characters and may only contain letters, digits, and hyphens.
55+
print("\n.. Create an External Key")
56+
key_name = "externalKeyNameAsync"
57+
external_key = ExternalKey(id="external-key-reference-id")
58+
key = await client.create_external_key(key_name, external_key=external_key)
59+
print(f"External key '{key.name}' was registered with external id '{key.properties.external_key.id}'.")
60+
print(f"Key type is '{key.key_type}' and key size is '{key.properties.key_size}'.")
61+
62+
# Read the registration back to confirm the external_key reference is round-tripped.
63+
print("\n.. Get the External Key by name")
64+
fetched = await client.get_key(key.name)
65+
print(f"Key with name '{fetched.name}' has external_key id '{fetched.properties.external_key.id}'.")
66+
print(f"Key type is '{fetched.key_type}' and key size is '{fetched.properties.key_size}'.")
67+
68+
# The external key registration is no longer used; delete it from the Managed HSM.
69+
# Deleting the registration does not delete the key material in the external HSM.
70+
print("\n.. Delete the External Key")
71+
await client.delete_key(key.name)
72+
print(f"Deleted external key '{key.name}'.")
73+
74+
# The deleted key registration still exists in the Managed HSM's soft-deleted state. Purge it to remove it permanently.
75+
print("\n.. Purge the deleted External Key")
76+
await client.purge_deleted_key(key.name)
77+
print(f"Purged external key '{key.name}'.")
78+
79+
print("\nrun_sample done")
80+
await credential.close()
81+
await client.close()
82+
83+
84+
if __name__ == "__main__":
85+
asyncio.run(run_sample())

0 commit comments

Comments
 (0)