Azure Key Vault helps solve the following problems:
- Managed HSM security ___domain management (this library) - securely download and restore a managed HSM's security ___domain
- Cryptographic key management (azure-keyvault-keys)- create, store, and control access to the keys used to encrypt your data
- Secrets management (azure-keyvault-secrets) - securely store and control access to tokens, passwords, certificates, API keys, and other secrets
- Certificate management (azure-keyvault-certificates) - create, manage, and deploy public and private SSL/TLS certificates
- Vault administration (azure-keyvault-administration) - role-based access control (RBAC), and vault-level backup and restore options
Source code | Package (PyPI) | API reference documentation | Key Vault documentation | Managed HSM documentation | Samples
Getting started
Install the package
Install azure-keyvault-securitydomain and azure-identity with pip:
python -m pip install azure-keyvault-securitydomain azure-identity
azure-identity is used for Microsoft Entra ID authentication as demonstrated below.
Prequisites
- Python 3.9 or later
- An Azure subscription
- An existing Key Vault Managed HSM. If you need to create a Managed HSM, you can do so using the Azure CLI by following the steps in this document.
Authenticate the client
In order to interact with the Azure Key Vault service, you will need an instance of a SecurityDomainClient, as well as a vault URL and a credential object. This document demonstrates using a DefaultAzureCredential, which is appropriate for most scenarios. We recommend using a managed identity for authentication in production environments.
See azure-identity documentation for more information about other methods of authentication and their corresponding credential types.
Create a client
After configuring your environment for the DefaultAzureCredential to use a suitable method of
authentication, you can do the following to create a security ___domain client (replacing the value of VAULT_URL with
your vault's URL):
from azure.identity import DefaultAzureCredential
from azure.keyvault.securitydomain import SecurityDomainClient
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecurityDomainClient(vault_url=VAULT_URL, credential=credential)
NOTE: For an asynchronous client, import
azure.keyvault.securitydomain.aio'sSecurityDomainClientinstead.
Key concepts
Security ___domain
To operate, a managed HSM must have a security ___domain. The security ___domain is an encrypted blob file that contains artifacts like the HSM backup, user credentials, the signing key, and the data encryption key that's unique to the managed HSM. For more information, please see service documentation.
SecurityDomainClient
A SecurityDomainClient can download and upload managed HSM security domains and get transfer keys.
Download operation
A download operation retrieves the security ___domain of a managed HSM. This can be used to activate a provisioned managed HSM.
Upload operation
An upload operation restores a managed HSM using a provided security ___domain.
Transfer key
A transfer key, or exchange key, is used to encrypt a security ___domain before uploading it to a managed HSM. For more information, please see the disaster recovery guide.
Examples
This section contains code snippets covering common tasks:
Download a security ___domain
begin_download can be used by a SecurityDomainClient to fetch a managed HSM's security ___domain, and this will also
activate a provisioned managed HSM. By default, the poller returned by this operation will poll on the managed HSM's
activation status, finishing when it's activated. To return immediately with the security ___domain object without waiting
for activation, you can pass the keyword argument skip_activation_polling=True.
from azure.keyvault.securitydomain.models import SecurityDomain
security_domain: SecurityDomain = client.begin_download(certificate_info=certs_object).result()
assert security_domain.value
print("The managed HSM is now active.")
Get a transfer key
Using a different managed HSM than the one the security ___domain was downloaded from, get_transfer_key can be used by
a SecurityDomainClient to fetch a transfer key (also known as an exchange key).
from azure.keyvault.securitydomain.models import TransferKey
NEW_VAULT_URL = os.environ["NEW_VAULT_URL"]
upload_client = SecurityDomainClient(vault_url=NEW_VAULT_URL, credential=credential)
transfer_key: TransferKey = upload_client.get_transfer_key()
assert transfer_key.transfer_key_jwk
Upload a security ___domain
begin_upload can be used by a SecurityDomainClient to restore a different managed HSM with a security ___domain, for
example for disaster recovery. Like the download operation this will activate a provisioned managed HSM, but the poller
will return None if successful (and an error if unsuccessful) instead of the security ___domain object.
from azure.keyvault.securitydomain.models import SecurityDomainOperationStatus
result: SecurityDomainOperationStatus = upload_client.begin_upload(security_domain=result).result()
print("The managed HSM has been successfully restored with the security ___domain.")
Troubleshooting
See the Azure Key Vault SDK's troubleshooting guide for details on how to diagnose various failure scenarios.
Next steps
Samples are available in the Azure SDK for Python GitHub repository. These samples provide example code for the following scenarios:
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
