{"id":5575,"library":"azure-keyvault-securitydomain","title":"Azure Key Vault Security Domain Client Library","description":"The Azure Key Vault Security Domain client library for Python allows developers to securely manage the security domain of an Azure Key Vault Managed HSM. This includes operations to download and restore a Managed HSM's security domain, which is crucial for establishing ownership, setting cryptographic boundaries, and enabling disaster recovery. The library is currently in a beta release, version `1.0.0b1`, as part of the broader Azure SDK for Python, which follows a regular release cadence with preview versions often preceding stable releases.","status":"active","version":"1.0.0b1","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk","tags":["Azure","Key Vault","Security Domain","cloud","security","HSM","cryptography"],"install":[{"cmd":"pip install azure-keyvault-securitydomain azure-identity","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for running the library.","package":"python","version":">=3.9","optional":false},{"reason":"Required for authenticating to Azure services, including Azure Key Vault Managed HSM.","package":"azure-identity","optional":false}],"imports":[{"symbol":"SecurityDomainClient","correct":"from azure.keyvault.securitydomain import SecurityDomainClient"},{"symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"},{"note":"Used for representing JWK for security domain operations.","symbol":"SecurityDomainJsonWebKey","correct":"from azure.keyvault.securitydomain.models import SecurityDomainJsonWebKey"},{"note":"Model for a security domain object, often returned by download operations.","symbol":"SecurityDomain","correct":"from azure.keyvault.securitydomain.models import SecurityDomain"},{"note":"Model for the status of a security domain operation.","symbol":"SecurityDomainOperationStatus","correct":"from azure.keyvault.securitydomain.models import SecurityDomainOperationStatus"}],"quickstart":{"code":"import os\nfrom azure.identity import DefaultAzureCredential\nfrom azure.keyvault.securitydomain import SecurityDomainClient\n\n# Set your Managed HSM URL as an environment variable\n# Example: 'https://my-managed-hsm.managedhsm.azure.net/'\nVAULT_URL = os.environ.get(\"AZURE_MANAGEDHSM_URL\", \"<your-managed-hsm-url>\")\n\n# --- Prerequisites for actual operations ---\n# For actual download/upload, you would need:\n# 1. An active Azure subscription.\n# 2. An existing Azure Key Vault Managed HSM (not a standard Key Vault).\n# 3. RSA key pairs (public keys for 'sd_wrapping_keys') and a specified quorum.\n# 4. Proper RBAC permissions for your identity to perform security domain operations.\n#    (e.g., 'Managed HSM Security Domain Contributor' role).\n\nif VAULT_URL == '<your-managed-hsm-url>':\n    print(\"Please set the AZURE_MANAGEDHSM_URL environment variable or replace the placeholder.\")\n    exit(1)\n\ntry:\n    # Authenticate using DefaultAzureCredential\n    # This will try various methods: environment variables, managed identity, Azure CLI, etc.\n    credential = DefaultAzureCredential()\n    \n    # Create a SecurityDomainClient\n    client = SecurityDomainClient(vault_url=VAULT_URL, credential=credential)\n    print(f\"Successfully created SecurityDomainClient for: {VAULT_URL}\")\n\n    # --- Example: (Conceptual) Download a security domain ---\n    # This operation requires 'certificate_info' (public keys) and 'quorum'.\n    # It's a long-running operation, so 'begin_download' returns a poller.\n    # For a real scenario, 'certs_object' would be a list of SecurityDomainJsonWebKey objects\n    # and 'quorum' would be an integer.\n    # Example: certs_object = [SecurityDomainJsonWebKey(...), ...]\n    #          quorum = 2\n    # poller = client.begin_download(certificate_info=certs_object, quorum=quorum)\n    # security_domain = poller.result()\n    # print(\"Security Domain downloaded.\")\n\n    # For demonstration, we'll just show client creation and a dummy print.\n    print(\"Client created. Actual security domain operations require a Managed HSM and specific certificate setup.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to instantiate the `SecurityDomainClient` using `DefaultAzureCredential` for authentication. It highlights the prerequisites for performing actual security domain operations like downloading, which include an Azure Key Vault Managed HSM and specific key management for encryption."},"warnings":[{"fix":"Monitor release notes for subsequent versions and update code as necessary. Test thoroughly when upgrading.","message":"As a beta library (`1.0.0b1`), `azure-keyvault-securitydomain` is subject to breaking changes in future releases before reaching general availability. APIs, models, and behaviors may change without backward compatibility guarantees.","severity":"breaking","affected_versions":"All beta versions (e.g., 1.0.0b1)"},{"fix":"Ensure you are interacting with an Azure Key Vault Managed HSM resource. Create one if necessary via Azure CLI or Azure Portal.","message":"This library is specifically designed for Azure Key Vault Managed HSMs, not standard Azure Key Vaults. Attempting to use it with a standard Key Vault will result in errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the `azure-identity` documentation for setting up appropriate credentials for your environment. Ensure your identity has the necessary RBAC roles (e.g., 'Managed HSM Security Domain Contributor') on the Managed HSM.","message":"Authentication with Azure services, including Managed HSM, requires proper configuration for `DefaultAzureCredential`. In development, this often means logging in via Azure CLI or setting environment variables (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`). In production, Managed Identities are recommended.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always call `.result()` on the `LROPoller` returned by `begin_download`, `begin_upload`, etc., to get the operation's outcome. Example: `security_domain = client.begin_download(...).result()`.","message":"Security domain operations (e.g., download, upload) are long-running and return `LROPoller` objects. You must call `.result()` on the poller to wait for the operation to complete and retrieve the final result or status.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate access control for your Managed HSMs to Azure RBAC and ensure your deployment scripts use API version `2026-02-01` or later for Key Vault/Managed HSM creation and management. Review and assign appropriate RBAC roles.","message":"Azure Key Vault is shifting to Azure Role-Based Access Control (RBAC) as the default access control model, deprecating older vault access policies. While this isn't a direct API change in `azure-keyvault-securitydomain`, it critically impacts how permissions are granted to your application's identity accessing the Managed HSM. Older API versions will be retired by February 27, 2027.","severity":"breaking","affected_versions":"Impacts all Key Vault users; specific API version `2026-02-01` and later become default."},{"fix":"Generate the required number of RSA key pairs (typically 3-10) and manage their private keys securely offline. Extract the public keys (e.g., from self-signed certificates) and pass them to the `certificate_info` parameter, along with the `quorum` (minimum number of private keys needed for decryption).","message":"Actual `begin_download` and `begin_upload` operations require a collection of RSA public keys (certificates) and a 'quorum' to encrypt/decrypt the security domain using Shamir's Secret Sharing Algorithm. Generating and managing these keys securely is a complex prerequisite.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor for library updates that address typing fixes. If encountering issues, temporarily adjust `pyright` configuration or type-checking strictness, or contribute fixes to the Azure SDK for Python.","message":"Typing issues have been reported for `azure-keyvault-securitydomain` with specific `pyright` versions (e.g., 1.1.408). This could lead to static analysis failures or runtime issues in environments with strict type checking.","severity":"gotcha","affected_versions":"1.0.0b1 (and potentially future beta versions)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}