KeyClient Classe

Uma interface de alto nível para gerenciar as chaves de um cofre.

Herança

azure.keyvault.keys._shared.client_base.KeyVaultClientBase

KeyClient

Construtor

KeyClient(vault_url: str, credential: TokenCredential, **kwargs)

Parâmetros

vault_url

str

Obrigatório

URL do cofre que o cliente acessará. Isso também é chamado de "Nome DNS" do cofre. Você deve validar se essa URL faz referência a um recurso de HSM Key Vault ou gerenciado válido. Para obter detalhes, consulte https://aka.ms/azsdk/blog/vault-uri.

credential

TokenCredential

Obrigatório

Um objeto que pode fornecer um token de acesso para o cofre, como uma credencial de identity

api_version

ApiVersion

Versão da API de serviço a ser usada. O padrão é o mais recente.

verify_challenge_resource

bool

Se o recurso de desafio de autenticação deve ser verificado corresponde ao Key Vault ou ao domínio HSM Gerenciado. O padrão é True.

Métodos

backup_key	Faça backup de uma chave em um formulário protegido utilizável somente por Key Vault do Azure. Requer permissão de backup/chaves. Isso se destina a permitir a cópia de uma chave de um cofre para outro. Ambos os cofres devem pertencer à mesma assinatura do Azure. Além disso, o backup/restauração não pode ser executado entre limites geopolíticos. Por exemplo, um backup de um cofre em uma região dos EUA não pode ser restaurado para um cofre em uma região da UE.
begin_delete_key	Exclua todas as versões de uma chave e seu material criptográfico. Requer permissão de exclusão/chaves. Quando esse método retorna Key Vault começou a excluir a chave. A exclusão pode levar vários segundos em um cofre com a exclusão reversível habilitada. Portanto, esse método retorna um poller que permite aguardar a conclusão da exclusão.
begin_recover_deleted_key	Recupere uma chave excluída para sua versão mais recente. Possível somente em um cofre com exclusão reversível habilitada. Requer permissão de recuperação/chaves. Quando esse método retorna Key Vault começou a recuperar a chave. A recuperação pode levar vários segundos. Portanto, esse método retorna um poller que permite aguardar a conclusão da recuperação. A espera só é necessária quando você deseja usar a chave recuperada em outra operação imediatamente.
close	Feche soquetes abertos pelo cliente. Chamar esse método é desnecessário ao usar o cliente como um gerenciador de contexto.
create_ec_key	Crie uma nova chave de curva elíptica ou, se name já estiver em uso, crie uma nova versão da chave. requer a permissão chaves/criar.
create_key	Crie uma chave ou, se name já estiver em uso, crie uma nova versão da chave. Requer permissão de criação/chaves.
create_oct_key	Crie uma nova chave de sequência de octeto (simétrica) ou, se name estiver em uso, crie uma nova versão da chave. requer a permissão chaves/criar.
create_rsa_key	Criar uma nova chave RSA ou, se name já estiver em uso, criar uma nova versão da chave requer a permissão chaves/criar.
get_cryptography_client	Obtém um CryptographyClient para a chave fornecida.
get_deleted_key	Obtenha uma chave excluída. Possível somente em um cofre com exclusão reversível habilitada. Requer permissão de obtenção/chaves.
get_key	Obtenha os atributos de uma chave e, se for uma chave assimétrica, seu material público. Requer permissão de obtenção/chaves.
get_key_rotation_policy	Obtenha a política de rotação de uma chave de Key Vault.
get_random_bytes	Obtenha o número solicitado de bytes aleatórios de um HSM gerenciado.
import_key	Importe uma chave criada externamente. Requer permissão de importação/chaves. Se name já estiver em uso, a chave será importada como uma nova versão.
list_deleted_keys	Liste todas as chaves excluídas, incluindo a parte pública de cada uma. Possível somente em um cofre com exclusão reversível habilitada. Requer permissão de chaves/lista.
list_properties_of_key_versions	Liste os identificadores e as propriedades das versões de uma chave. Requer permissão de chaves/lista.
list_properties_of_keys	Listar identificadores e propriedades de todas as chaves no cofre. Requer permissão de chaves/lista.
purge_deleted_key	Exclui permanentemente uma chave excluída. Só é possível em um cofre com exclusão reversível habilitada. Executa uma exclusão irreversível da chave especificada, sem possibilidade de recuperação. A operação não estará disponível se o recovery_level não especificar "Purgável". Esse método só é necessário para limpar uma chave antes de seu scheduled_purge_date. Requer permissão de limpeza/chaves.
release_key	Libera uma chave. A operação de chave de liberação é aplicável a todos os tipos de chave. A chave de destino deve ser marcada como exportável. Essa operação requer a permissão de liberação/chaves.
restore_key_backup	Restaure um backup de chave para o cofre. Requer permissão de restauração/chaves. Isso importa todas as versões da chave, com seu nome, atributos e políticas de controle de acesso. Se o nome da chave já estiver em uso, a restauração dela falhará. Além disso, o cofre de destino deve pertencer à mesma assinatura do Microsoft Azure que o cofre de origem.
rotate_key	Gire a chave com base na política de chave gerando uma nova versão da chave. Essa operação requer a permissão de rotação/teclas.
send_request	Executa uma solicitação de rede usando o pipeline existente do cliente. A URL de solicitação pode ser relativa à URL do cofre. A versão da API de serviço usada para a solicitação é a mesma do cliente, a menos que especificado de outra forma. Esse método não será gerado se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta retornado. Para obter mais informações sobre como enviar solicitações personalizadas com esse método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.
update_key_properties	Altere as propriedades de uma chave (não seu material criptográfico). Requer permissão de atualização/chaves.
update_key_rotation_policy	Atualizações a política de rotação de uma chave de Key Vault. Essa operação requer a permissão de atualização/chaves.

backup_key

Faça backup de uma chave em um formulário protegido utilizável somente por Key Vault do Azure.

Requer permissão de backup/chaves.

Isso se destina a permitir a cópia de uma chave de um cofre para outro. Ambos os cofres devem pertencer à mesma assinatura do Azure. Além disso, o backup/restauração não pode ser executado entre limites geopolíticos. Por exemplo, um backup de um cofre em uma região dos EUA não pode ser restaurado para um cofre em uma região da UE.

backup_key(name: str, **kwargs) -> bytes

Parâmetros

name

str

Obrigatório

O nome da chave a ser backup

Tipo de retorno

bytes

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

begin_delete_key

Exclua todas as versões de uma chave e seu material criptográfico.

Requer permissão de exclusão/chaves. Quando esse método retorna Key Vault começou a excluir a chave. A exclusão pode levar vários segundos em um cofre com a exclusão reversível habilitada. Portanto, esse método retorna um poller que permite aguardar a conclusão da exclusão.

begin_delete_key(name: str, **kwargs) -> LROPoller[DeletedKey]

Parâmetros

name

str

Obrigatório

O nome da chave a ser excluída.

Retornos

Um sondador para a operação de exclusão de chave. O método de resultado do poller retorna o DeletedKey sem aguardar a conclusão da exclusão. Se o cofre tiver a exclusão reversível habilitada e você quiser excluir permanentemente a chave com purge_deleted_key, chame o método de espera do poller primeiro. Ele será bloqueado até que a exclusão seja concluída. O método de espera requer permissão de obtenção/chaves.

Tipo de retorno

LROPoller[DeletedKey]

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

begin_recover_deleted_key

Recupere uma chave excluída para sua versão mais recente. Possível somente em um cofre com exclusão reversível habilitada.

Requer permissão de recuperação/chaves.

Quando esse método retorna Key Vault começou a recuperar a chave. A recuperação pode levar vários segundos. Portanto, esse método retorna um poller que permite aguardar a conclusão da recuperação. A espera só é necessária quando você deseja usar a chave recuperada em outra operação imediatamente.

begin_recover_deleted_key(name: str, **kwargs) -> LROPoller[KeyVaultKey]

Parâmetros

name

str

Obrigatório

O nome da chave excluída a ser recuperada

Retornos

Um sondador para a operação de recuperação. O método de resultado do poller retorna o recuperado KeyVaultKey sem aguardar a conclusão da recuperação. Se você quiser usar a chave recuperada imediatamente, chame o método de espera do sondador, que bloqueia até que a chave esteja pronta para uso. O método de espera requer permissão de obtenção/chaves.

Tipo de retorno

LROPoller[KeyVaultKey]

Exceções

HttpResponseError

close

Feche soquetes abertos pelo cliente.

Chamar esse método é desnecessário ao usar o cliente como um gerenciador de contexto.

close() -> None

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

create_ec_key

Crie uma nova chave de curva elíptica ou, se name já estiver em uso, crie uma nova versão da chave.

requer a permissão chaves/criar.

create_ec_key(name: str, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

O nome da nova chave.

curve

KeyCurveName ou str ou None

Nome da curva elíptica. O padrão é a curva elíptica NIST P-256.

key_operations

list[KeyOperation ou str] ou None

Operações de chave permitidas

hardware_protected

bool ou None

Se a chave deve ser criada em um módulo de segurança de hardware. Assume o padrão de False.

enabled

bool ou None

Se a chave está habilitada para uso.

tags

dict[str, str] ou None

Metadados específicos do aplicativo na forma de pares chave-valor.

not_before

datetime ou None

Não antes da data da chave em UTC

expires_on

datetime ou None

Data de expiração da chave em UTC

exportable

bool ou None

Se a chave privada pode ser exportada.

release_policy

KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Retornos

A chave criada

Tipo de retorno

KeyVaultKey

Exceções

HttpResponseError

create_key

Crie uma chave ou, se name já estiver em uso, crie uma nova versão da chave.

Requer permissão de criação/chaves.

create_key(name: str, key_type: str | KeyType, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

O nome da nova chave.

key_type

KeyType ou str

Obrigatório

O tipo de chave a ser criada

size

int ou None

Tamanho da chave em bits. Aplica-se somente ao RSA e às chaves simétricas. Considere usar create_rsa_key ou create_oct_key em vez disso.

curve

KeyCurveName ou str ou None

Nome da curva elíptica. Aplica-se somente a teclas de curva elípticas. O padrão é a curva elíptica NIST P-256. Para criar uma chave de curva elíptica, considere usar create_ec_key em vez disso.

public_exponent

int ou None

O expoente público RSA a ser usado. Aplica-se somente a chaves RSA criadas em um HSM Gerenciado.

key_operations

list[KeyOperation ou str] ou None

Operações de chave permitidas

enabled

bool ou None

Se a chave está habilitada para uso.

tags

dict[str, str] ou None

Metadados específicos do aplicativo na forma de pares chave-valor.

not_before

datetime ou None

Não antes da data da chave em UTC

expires_on

datetime ou None

Data de expiração da chave em UTC

exportable

bool ou None

Se a chave privada pode ser exportada.

release_policy

KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Retornos

A chave criada

Tipo de retorno

KeyVaultKey

Exceções

HttpResponseError

create_oct_key

Crie uma nova chave de sequência de octeto (simétrica) ou, se name estiver em uso, crie uma nova versão da chave.

requer a permissão chaves/criar.

create_oct_key(name: str, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

O nome da nova chave.

size

int ou None

Tamanho da chave em bits, por exemplo, 128, 192 ou 256.

key_operations

list[KeyOperation ou str] ou None

Operações de chave permitidas.

hardware_protected

bool ou None

Se a chave deve ser criada em um módulo de segurança de hardware. Assume o padrão de False.

enabled

bool ou None

Se a chave está habilitada para uso.

tags

dict[str, str] ou None

Metadados específicos do aplicativo na forma de pares chave-valor.

not_before

datetime ou None

Não antes da data da chave em UTC

expires_on

datetime ou None

Data de expiração da chave em UTC

exportable

bool ou None

Se a chave pode ser exportada.

release_policy

KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Retornos

A chave criada

Tipo de retorno

KeyVaultKey

Exceções

HttpResponseError

create_rsa_key

Criar uma nova chave RSA ou, se name já estiver em uso, criar uma nova versão da chave

requer a permissão chaves/criar.

create_rsa_key(name: str, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

O nome da nova chave.

size

int ou None

Tamanho da chave em bits, por exemplo, 2048, 3072 ou 4096.

public_exponent

int ou None

O expoente público RSA a ser usado. Aplica-se somente a chaves RSA criadas em um HSM Gerenciado.

hardware_protected

bool ou None

Se a chave deve ser criada em um módulo de segurança de hardware. Assume o padrão de False.

key_operations

list[KeyOperation ou str] ou None

Operações de chave permitidas

enabled

bool ou None

Se a chave está habilitada para uso.

tags

dict[str, str] ou None

Metadados específicos do aplicativo na forma de pares chave-valor.

not_before

datetime ou None

Não antes da data da chave em UTC

expires_on

datetime ou None

Data de expiração da chave em UTC

exportable

bool ou None

Se a chave privada pode ser exportada.

release_policy

KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Retornos

A chave criada

Tipo de retorno

KeyVaultKey

Exceções

HttpResponseError

get_cryptography_client

Obtém um CryptographyClient para a chave fornecida.

get_cryptography_client(key_name: str, **kwargs) -> CryptographyClient

Parâmetros

key_name

str

Obrigatório

O nome da chave usada para executar operações criptográficas.

key_version

str

Versão opcional da chave usada para executar operações criptográficas.

Retornos

Um CryptographyClient que usa as mesmas opções, credenciais e cliente HTTP que este KeyClient.

Tipo de retorno

CryptographyClient

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

get_deleted_key

Obtenha uma chave excluída. Possível somente em um cofre com exclusão reversível habilitada.

Requer permissão de obtenção/chaves.

get_deleted_key(name: str, **kwargs) -> DeletedKey

Parâmetros

name

str

Obrigatório

O nome da chave

Retornos

A chave excluída

Tipo de retorno

DeletedKey

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

get_key

Obtenha os atributos de uma chave e, se for uma chave assimétrica, seu material público.

Requer permissão de obtenção/chaves.

get_key(name: str, version: str | None = None, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

O nome da chave a ser obtido.

version

str ou None

Obrigatório

(opcional) Uma versão específica da chave a ser obtido. Se não for especificado, obterá a versão mais recente da chave.

Tipo de retorno

KeyVaultKey

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

get_key_rotation_policy

Obtenha a política de rotação de uma chave de Key Vault.

get_key_rotation_policy(key_name: str, **kwargs) -> KeyRotationPolicy

Parâmetros

key_name

str

Obrigatório

O nome da chave.

Retornos

A política de rotação de chave.

Tipo de retorno

KeyRotationPolicy

Exceções

*azure.core.exceptions.HttpResponseError*

get_random_bytes

Obtenha o número solicitado de bytes aleatórios de um HSM gerenciado.

get_random_bytes(count: int, **kwargs) -> bytes

Parâmetros

count

int

Obrigatório

O número solicitado de bytes aleatórios.

Retornos

Os bytes aleatórios.

Tipo de retorno

bytes

Exceções

ValueError

se menos de um byte aleatório for solicitado,

HttpResponseError

para outros erros

import_key

Importe uma chave criada externamente.

Requer permissão de importação/chaves. Se name já estiver em uso, a chave será importada como uma nova versão.

import_key(name: str, key: JsonWebKey, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

Nome da chave importada

key

JsonWebKey

Obrigatório

A chave da Web JSON a ser importada

hardware_protected

bool ou None

Se a chave deve ser apoiada por um módulo de segurança de hardware

enabled

bool ou None

Se a chave está habilitada para uso.

tags

dict[str, str] ou None

Metadados específicos do aplicativo na forma de pares chave-valor.

not_before

datetime ou None

Não antes da data da chave em UTC

expires_on

datetime ou None

Data de expiração da chave em UTC

exportable

bool ou None

Se a chave privada pode ser exportada.

release_policy

KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Retornos

A chave importada

Tipo de retorno

KeyVaultKey

Exceções

HttpResponseError

list_deleted_keys

Liste todas as chaves excluídas, incluindo a parte pública de cada uma. Possível somente em um cofre com exclusão reversível habilitada.

Requer permissão de chaves/lista.

list_deleted_keys(**kwargs) -> ItemPaged[DeletedKey]

Retornos

Um iterador de chaves excluídas

Tipo de retorno

ItemPaged[DeletedKey]

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

list_properties_of_key_versions

Liste os identificadores e as propriedades das versões de uma chave.

Requer permissão de chaves/lista.

list_properties_of_key_versions(name: str, **kwargs) -> ItemPaged[KeyProperties]

Parâmetros

name

str

Obrigatório

O nome da chave

Retornos

Um iterador de chaves sem seu material criptográfico

Tipo de retorno

ItemPaged[KeyProperties]

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

list_properties_of_keys

Listar identificadores e propriedades de todas as chaves no cofre.

Requer permissão de chaves/lista.

list_properties_of_keys(**kwargs) -> ItemPaged[KeyProperties]

Retornos

Um iterador de chaves sem seu material criptográfico ou informações de versão

Tipo de retorno

ItemPaged[KeyProperties]

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

purge_deleted_key

Exclui permanentemente uma chave excluída. Só é possível em um cofre com exclusão reversível habilitada.

Executa uma exclusão irreversível da chave especificada, sem possibilidade de recuperação. A operação não estará disponível se o recovery_level não especificar "Purgável". Esse método só é necessário para limpar uma chave antes de seu scheduled_purge_date.

Requer permissão de limpeza/chaves.

purge_deleted_key(name: str, **kwargs) -> None

Parâmetros

name

str

Obrigatório

O nome da chave excluída a ser limpa

Retornos

Nenhum

Exceções

HttpResponseError

Exemplos

   # if the vault has soft-delete enabled, purge permanently deletes a deleted key
   # (with soft-delete disabled, begin_delete_key is permanent)
   key_client.purge_deleted_key("key-name")

release_key

Libera uma chave.

A operação de chave de liberação é aplicável a todos os tipos de chave. A chave de destino deve ser marcada como exportável. Essa operação requer a permissão de liberação/chaves.

release_key(name: str, target_attestation_token: str, **kwargs) -> ReleaseKeyResult

Parâmetros

name

str

Obrigatório

O nome da chave a ser obtido.

target_attestation_token

str

Obrigatório

A asserção de atestado para o destino da versão da chave.

version

str ou None

Uma versão específica da chave a ser lançada. Se não for especificado, a versão mais recente será lançada.

algorithm

str ou KeyExportEncryptionAlgorithm ou None

O algoritmo de criptografia a ser usado para proteger o material de chave liberado.

nonce

str ou None

Um nó fornecido pelo cliente para atualização.

Retornos

O resultado da versão da chave.

Tipo de retorno

ReleaseKeyResult

Exceções

HttpResponseError

restore_key_backup

Restaure um backup de chave para o cofre.

Requer permissão de restauração/chaves.

Isso importa todas as versões da chave, com seu nome, atributos e políticas de controle de acesso. Se o nome da chave já estiver em uso, a restauração dela falhará. Além disso, o cofre de destino deve pertencer à mesma assinatura do Microsoft Azure que o cofre de origem.

restore_key_backup(backup: bytes, **kwargs) -> KeyVaultKey

Parâmetros

backup

bytes

Obrigatório

Um backup de chave conforme retornado por backup_key

Retornos

A chave restaurada

Tipo de retorno

KeyVaultKey

Exceções

ResourceExistsError

se o nome da chave de backup já estiver em uso,

HttpResponseError

para outros erros

rotate_key

Gire a chave com base na política de chave gerando uma nova versão da chave.

Essa operação requer a permissão de rotação/teclas.

rotate_key(name: str, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

O nome da chave a ser girada.

Retornos

A nova versão da chave girada.

Tipo de retorno

KeyVaultKey

Exceções

HttpResponseError

send_request

Executa uma solicitação de rede usando o pipeline existente do cliente.

A URL de solicitação pode ser relativa à URL do cofre. A versão da API de serviço usada para a solicitação é a mesma do cliente, a menos que especificado de outra forma. Esse método não será gerado se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta retornado. Para obter mais informações sobre como enviar solicitações personalizadas com esse método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.

send_request(request: HttpRequest, *, stream: bool = False, **kwargs) -> HttpResponse

Parâmetros

request

HttpRequest

Obrigatório

A solicitação de rede que você deseja fazer.

stream

bool

Se o conteúdo da resposta será transmitido. Usa False como padrão.

Retornos

A resposta da chamada de rede. Não faz tratamento de erros em sua resposta.

Tipo de retorno

HttpResponse

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

update_key_properties

Altere as propriedades de uma chave (não seu material criptográfico).

Requer permissão de atualização/chaves.

update_key_properties(name: str, version: str | None = None, **kwargs) -> KeyVaultKey

Parâmetros

name

str

Obrigatório

O nome da chave a ser atualizada

version

str ou None

Obrigatório

(opcional) A versão da chave a ser atualizada. Se não for especificado, a versão mais recente será atualizada.

key_operations

list[KeyOperation ou str] ou None

Operações de chave permitidas

enabled

bool ou None

Se a chave está habilitada para uso.

tags

dict[str, str] ou None

Metadados específicos do aplicativo na forma de pares chave-valor.

not_before

datetime ou None

Não antes da data da chave em UTC

expires_on

datetime ou None

Data de expiração da chave em UTC

release_policy

KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Retornos

A chave atualizada

Tipo de retorno

KeyVaultKey

Exceções

ResourceNotFoundError

se a chave não existir,

HttpResponseError

para outros erros

update_key_rotation_policy

Atualizações a política de rotação de uma chave de Key Vault.

Essa operação requer a permissão de atualização/chaves.

update_key_rotation_policy(key_name: str, policy: KeyRotationPolicy, **kwargs) -> KeyRotationPolicy

Parâmetros

key_name

str

Obrigatório

O nome da chave no cofre fornecido.

policy

KeyRotationPolicy

Obrigatório

A nova política de rotação para a chave.

lifetime_actions

list[KeyRotationLifetimeAction]

Ações que serão executadas por Key Vault ao longo do tempo de vida de uma chave. Isso substituirá as ações de tempo de vida do fornecido policy.

expires_in

str

A hora de expiração da política que será aplicada em novas versões de chave, definida como uma duração ISO 8601. Por exemplo: 90 dias é "P90D", 3 meses é "P3M" e 48 horas é "PT48H". Consulte Wikipédia para obter mais informações sobre as durações iso 8601. Isso substituirá a hora de expiração do fornecido policy.

Retornos

A política de rotação atualizada.

Tipo de retorno

KeyRotationPolicy

Exceções

HttpResponseError

Atributos

vault_url