tessl/pypi-azure-keyvault

Microsoft Azure Key Vault Client Libraries for Python providing unified access to keys, secrets, and certificates

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Key Vault Administration

Name: tessl/pypi-azure-keyvault
Author: tessl

Azure Key Vault administration capabilities for managing Managed HSM instances. Provides role-based access control (RBAC) management and full HSM backup/restore operations. These administrative functions are essential for enterprise HSM deployments requiring granular permission management and disaster recovery capabilities.

Capabilities

Access Control Client

Manages role assignments and role definitions for Key Vault Managed HSM instances.

class KeyVaultAccessControlClient:
    def __init__(self, vault_url: str, credential, **kwargs):
        """
        Initialize KeyVaultAccessControlClient for RBAC management.
        
        Parameters:
        - vault_url: str, Managed HSM URL (https://hsm-name.managedhsm.azure.net/)
        - credential: Azure credential object for authentication
        - api_version: ApiVersion, API version to use (default: latest)
        - **kwargs: Additional configuration options
        """

    def close(self) -> None:
        """Close the client and release resources."""

Role Assignment Management

Create, retrieve, and manage role assignments for HSM access control.

def create_role_assignment(self, role_scope: KeyVaultRoleScope, role_definition_id: str, principal_id: str, **kwargs) -> KeyVaultRoleAssignment:
    """
    Create a new role assignment.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope of the role assignment (global or keys)
    - role_definition_id: str, ID of the role definition
    - principal_id: str, object ID of the principal (user, group, or service principal)
    - role_assignment_name: str, optional name for the assignment (UUID if not provided)
    
    Returns:
    KeyVaultRoleAssignment: The created role assignment
    """

def get_role_assignment(self, role_scope: KeyVaultRoleScope, role_assignment_name: str, **kwargs) -> KeyVaultRoleAssignment:
    """
    Get a specific role assignment.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope to search within
    - role_assignment_name: str, name of the role assignment
    
    Returns:
    KeyVaultRoleAssignment: The role assignment details
    """

def delete_role_assignment(self, role_scope: KeyVaultRoleScope, role_assignment_name: str, **kwargs) -> KeyVaultRoleAssignment:
    """
    Delete a role assignment.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope of the assignment
    - role_assignment_name: str, name of the assignment to delete
    
    Returns:
    KeyVaultRoleAssignment: The deleted assignment details
    """

def list_role_assignments(self, role_scope: KeyVaultRoleScope, **kwargs) -> ItemPaged[KeyVaultRoleAssignment]:
    """
    List all role assignments within a scope.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope to list assignments from
    
    Returns:
    ItemPaged[KeyVaultRoleAssignment]: Paged list of role assignments
    """

Role Definition Management

Create, retrieve, and manage custom role definitions for fine-grained access control.

def set_role_definition(self, role_scope: KeyVaultRoleScope, **kwargs) -> KeyVaultRoleDefinition:
    """
    Create or update a custom role definition.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope for the role definition
    - role_name: str, name of the custom role
    - description: str, description of the role
    - permissions: List[KeyVaultPermission], list of permissions for the role
    - assignable_scopes: List[KeyVaultRoleScope], scopes where role can be assigned
    - role_definition_name: str, optional UUID for the role definition
    
    Returns:
    KeyVaultRoleDefinition: The created or updated role definition
    """

def get_role_definition(self, role_scope: KeyVaultRoleScope, role_definition_name: str, **kwargs) -> KeyVaultRoleDefinition:
    """
    Get a specific role definition.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope to search within
    - role_definition_name: str, name of the role definition
    
    Returns:
    KeyVaultRoleDefinition: The role definition details
    """

def delete_role_definition(self, role_scope: KeyVaultRoleScope, role_definition_name: str, **kwargs) -> KeyVaultRoleDefinition:
    """
    Delete a custom role definition.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope of the role definition
    - role_definition_name: str, name of the role definition to delete
    
    Returns:
    KeyVaultRoleDefinition: The deleted role definition details
    """

def list_role_definitions(self, role_scope: KeyVaultRoleScope, **kwargs) -> ItemPaged[KeyVaultRoleDefinition]:
    """
    List all role definitions within a scope.
    
    Parameters:
    - role_scope: KeyVaultRoleScope, scope to list definitions from
    
    Returns:
    ItemPaged[KeyVaultRoleDefinition]: Paged list of role definitions
    """

Backup Client

Manages full HSM backup and restore operations for disaster recovery.

class KeyVaultBackupClient:
    def __init__(self, vault_url: str, credential, **kwargs):
        """
        Initialize KeyVaultBackupClient for HSM backup operations.
        
        Parameters:
        - vault_url: str, Managed HSM URL (https://hsm-name.managedhsm.azure.net/)
        - credential: Azure credential object for authentication
        - api_version: ApiVersion, API version to use (default: latest)
        - **kwargs: Additional configuration options
        """

    def close(self) -> None:
        """Close the client and release resources."""

HSM Backup Operations

Perform full HSM backup and restore operations.

def begin_backup(self, blob_storage_url: str, sas_token: str, **kwargs) -> LROPoller[KeyVaultBackupResult]:
    """
    Begin a full backup of the HSM.
    
    Parameters:
    - blob_storage_url: str, URL of the Azure Blob Storage container
    - sas_token: str, SAS token for accessing the storage container
    - use_managed_identity: bool, whether to use managed identity for storage access
    
    Returns:
    LROPoller[KeyVaultBackupResult]: Long-running operation for the backup
    """

def begin_restore(self, blob_storage_url: str, sas_token: str, folder_name: str, **kwargs) -> LROPoller[None]:
    """
    Begin restoring from a full HSM backup.
    
    Parameters:
    - blob_storage_url: str, URL of the Azure Blob Storage container
    - sas_token: str, SAS token for accessing the storage container  
    - folder_name: str, name of the backup folder to restore from
    - use_managed_identity: bool, whether to use managed identity for storage access
    
    Returns:
    LROPoller[None]: Long-running operation for the restore
    """

Administration Types

# Role assignment models
class KeyVaultRoleAssignment:
    assignment_id: str
    name: str  
    properties: KeyVaultRoleAssignmentProperties
    role_definition_id: str
    scope: str
    type: str

class KeyVaultRoleAssignmentProperties:
    principal_id: str
    role_definition_id: str
    scope: str

# Role definition models
class KeyVaultRoleDefinition:
    assignable_scopes: List[str]
    description: str
    id: str
    name: str
    permissions: List[KeyVaultPermission]
    role_name: str
    role_type: str
    type: str

class KeyVaultPermission:
    actions: List[str]
    data_actions: List[KeyVaultDataAction]
    not_actions: List[str]
    not_data_actions: List[KeyVaultDataAction]

# Backup models
class KeyVaultBackupResult:
    folder_url: str
    start_time: datetime
    end_time: datetime

# Enums
class KeyVaultRoleScope(str, Enum):
    GLOBAL = "/"
    KEYS = "/keys"

class KeyVaultDataAction(str, Enum):
    # HSM key operations
    READ_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/read/action"
    WRITE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/write/action"
    DELETE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/delete/action"
    ENCRYPT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/encrypt/action"
    DECRYPT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/decrypt/action"
    SIGN_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/sign/action"
    VERIFY_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/verify/action"
    WRAP_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/wrap/action"
    UNWRAP_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/unwrap/action"
    CREATE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/create"
    IMPORT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/import/action"
    EXPORT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/export/action"
    RELEASE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/release/action"
    ROTATE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/rotate/action"
    BACKUP_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/backup/action"
    RESTORE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/restore/action"
    RECOVER_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/recover/action"
    PURGE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/purge/action"
    
    # Role management
    READ_ROLE_DEFINITION = "Microsoft.KeyVault/managedHsm/roleDefinitions/read/action"
    WRITE_ROLE_DEFINITION = "Microsoft.KeyVault/managedHsm/roleDefinitions/write/action"
    DELETE_ROLE_DEFINITION = "Microsoft.KeyVault/managedHsm/roleDefinitions/delete/action"
    READ_ROLE_ASSIGNMENT = "Microsoft.KeyVault/managedHsm/roleAssignments/read/action"
    WRITE_ROLE_ASSIGNMENT = "Microsoft.KeyVault/managedHsm/roleAssignments/write/action"
    DELETE_ROLE_ASSIGNMENT = "Microsoft.KeyVault/managedHsm/roleAssignments/delete/action"
    
    # Backup operations  
    START_BACKUP = "Microsoft.KeyVault/managedHsm/backup/start/action"
    START_RESTORE = "Microsoft.KeyVault/managedHsm/restore/start/action"
    READ_BACKUP_STATUS = "Microsoft.KeyVault/managedHsm/backup/status/action"
    READ_RESTORE_STATUS = "Microsoft.KeyVault/managedHsm/restore/status/action"

Usage Examples

Setting up RBAC for HSM

from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.keyvault.administration import KeyVaultRoleScope, KeyVaultDataAction, KeyVaultPermission
from azure.identity import DefaultAzureCredential

# Initialize client
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
    vault_url="https://my-hsm.managedhsm.azure.net/",
    credential=credential
)

# Create a custom role for key operations
permissions = [KeyVaultPermission(
    data_actions=[
        KeyVaultDataAction.READ_HSM_KEY,
        KeyVaultDataAction.ENCRYPT_HSM_KEY,
        KeyVaultDataAction.DECRYPT_HSM_KEY
    ]
)]

role_definition = client.set_role_definition(
    role_scope=KeyVaultRoleScope.KEYS,
    role_name="KeyOperator",
    description="Can read and use keys for crypto operations",
    permissions=permissions
)

# Assign the role to a user
assignment = client.create_role_assignment(
    role_scope=KeyVaultRoleScope.KEYS,
    role_definition_id=role_definition.id,
    principal_id="user-object-id-here"
)

HSM Backup and Restore

from azure.keyvault.administration import KeyVaultBackupClient
from azure.identity import DefaultAzureCredential

# Initialize backup client
credential = DefaultAzureCredential()
backup_client = KeyVaultBackupClient(
    vault_url="https://my-hsm.managedhsm.azure.net/",
    credential=credential
)

# Start backup operation
backup_operation = backup_client.begin_backup(
    blob_storage_url="https://mystorageaccount.blob.core.windows.net/backups",
    sas_token="?sv=2019-12-12&ss=b&srt=sco&sp=rwdlacx&se=..."
)

# Wait for completion
backup_result = backup_operation.result()
print(f"Backup completed: {backup_result.folder_url}")

# Restore from backup
restore_operation = backup_client.begin_restore(
    blob_storage_url="https://mystorageaccount.blob.core.windows.net/backups",
    sas_token="?sv=2019-12-12&ss=b&srt=sco&sp=rwdlacx&se=...",
    folder_name="backup-folder-name"
)

restore_operation.result()  # Wait for restore to complete

Install with Tessl CLI