Biblioteca de clientes da Administração do Azure KeyVault para .NET – versão 4.3.0

O Azure Key Vault O HSM Gerenciado é um serviço de nuvem totalmente gerenciado, altamente disponível, de locatário único e compatível com padrões, que permite proteger chaves criptográficas para seus aplicativos de nuvem usando HSMs validados fips 140-2 nível 3.

Os clientes da biblioteca de administração do Azure Key Vault dão suporte a tarefas administrativas, como backup completo/restauração e RBAC (controle de acesso baseado em função) no nível da chave.

Código-fonte | Pacote (NuGet) | Documentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes de administração do Azure Key Vault para .NET com o NuGet:

dotnet add package Azure.Security.KeyVault.Administration

Pré-requisitos

• Uma assinatura do Azure.
• Um Key Vault existente do Azure. Se você precisar criar um Key Vault do Azure, poderá usar a CLI do Azure.
• Autorização para um Key Vault existente do Azure usando o RBAC (recomendado) ou o controle de acesso.

Para criar um recurso de HSM gerenciado, execute o seguinte comando da CLI:

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

Para obter <your-user-object-id> , você pode executar o seguinte comando da CLI:

az ad user show --id <your-user-principal> --query id

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, você precisará criar uma instância das classes de cliente abaixo. Você precisa de uma URL do cofre, que você pode ver como "Nome DNS" no portal e credenciais para instanciar um objeto cliente.

Os exemplos mostrados abaixo usam um DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. Além disso, recomendamos usar uma identidade gerenciada para autenticação em ambientes de produção. Você pode encontrar mais informações sobre diferentes maneiras de autenticação e seus tipos de credencial correspondentes na documentação da Identidade do Azure .

Para usar o DefaultAzureCredential provedor mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, primeiro você deve instalar o pacote Azure.Identity:

dotnet add package Azure.Identity

Ativar o HSM gerenciado

Todos os comandos do plano de dados ficam desabilitados até que o HSM seja ativado. Você não poderá criar chaves nem atribuir funções. Somente os administradores designados que foram atribuídos durante o comando create podem ativar o HSM. Para ativar o HSM, você deve baixar o domínio de segurança.

Para ativar seu HSM, você precisa:

• Um mínimo de 3 pares de chaves RSA (máximo de 10)
• Especifique o número mínimo de chaves necessárias para descriptografar o domínio de segurança (quorum)

Para ativar o HSM, você envia pelo menos três (máximo 10) chaves públicas RSA para o HSM. O HSM criptografa o domínio de segurança com essas chaves e o envia de volta. Depois que esse domínio de segurança for baixado com êxito, o HSM estará pronto para uso. Você também precisa especificar quorum, que é o número mínimo de chaves privadas necessárias para descriptografar o domínio de segurança.

O exemplo a seguir mostra como usar openssl para gerar três certificados autoassinados.

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

Use o comando az keyvault security-domain download para baixar o domínio de segurança e ativar o HSM gerenciado. O exemplo a seguir usa três pares de chaves RSA (somente chaves públicas são necessárias para esse comando) e define o quorum como 2.

az keyvault security-domain download --hsm-name <your-managed-hsm-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

Controlando o acesso ao HSM gerenciado

Os administradores designados atribuídos durante a criação são adicionados automaticamente à função interna "Administradores de HSM Gerenciados", que podem baixar um domínio de segurança e gerenciar funções para acesso ao plano de dados, entre outras permissões limitadas.

Para executar outras ações em chaves, você precisa atribuir entidades de segurança a outras funções, como "Usuário de Criptografia HSM Gerenciado", que pode executar operações de chave não destrutivas:

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

Leia as práticas recomendadas para proteger corretamente o HSM gerenciado.

Criar KeyVaultAccessControlClient

Instancie um DefaultAzureCredential para passar para o KeyVaultAccessControlClient. A mesma instância de uma credencial de token poderá ser usada com vários clientes se eles estiverem se autenticando com a mesma identidade.

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Criar KeyVaultBackupClient

Instancie um DefaultAzureCredential para passar para o KeyVaultBackupClient. A mesma instância de uma credencial de token poderá ser usada com vários clientes se eles estiverem se autenticando com a mesma identidade.

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Criar KeyVaultSettingClient

Instancie um DefaultAzureCredential para passar para o KeyVaultSettingsClient. A mesma instância de uma credencial de token poderá ser usada com vários clientes se eles estiverem se autenticando com a mesma identidade.

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Principais conceitos

KeyVaultRoleDefinition

Um KeyVaultRoleDefinition é uma coleção de permissões. Uma definição de função define as operações que podem ser executadas, como leitura, gravação e exclusão. Ele também pode definir as operações excluídas das operações permitidas.

KeyVaultRoleDefinitions pode ser listado e especificado como parte de um KeyVaultRoleAssignment.

KeyVaultRoleAssignment

Um KeyVaultRoleAssignment é a associação de um KeyVaultRoleDefinition a uma entidade de serviço. Eles podem ser criados, listados, buscados individualmente e excluídos.

KeyVaultAccessControlClient

Um KeyVaultAccessControlClient fornece operações síncronas e assíncronas, permitindo o gerenciamento de KeyVaultRoleDefinition objetos e KeyVaultRoleAssignment .

KeyVaultBackupClient

Um KeyVaultBackupClient fornece operações síncronas e assíncronas para executar backups de chave completa, restaurações de chave completa e restaurações seletivas de chave.

BackupOperation

Um BackupOperation representa uma operação de execução longa para um backup de chave completa.

RestoreOperation

Um RestoreOperation representa uma operação de execução longa para uma chave completa e uma restauração seletiva de chave.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções | do cliente Acessando a resposta | Operações de execução prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

O pacote Azure.Security.KeyVault.Administration dá suporte a APIs síncronas e assíncronas.

A seção a seguir fornece vários snippets de código usando o client criado acima para clientes de controle de acesso ou backup, abrangendo algumas das tarefas mais comuns relacionadas ao controle de acesso do Azure Key Vault:

Exemplos de sincronização

• Controle de acesso
  • Listando todas as definições de função
  • Listando todas as atribuições de função
  • Criando uma atribuição de função
  • Obtendo uma atribuição de função
  • Excluindo atribuições de função
• Backup e restauração
  • Executando um backup de chave completa
  • Executando uma restauração de chave completa

Exemplos assíncronos

• Controle de acesso
  • Listando todas as definições de função
  • Listando todas as atribuições de função
  • Criando uma atribuição de função
  • Obtendo uma atribuição de função
  • Excluindo atribuições de função
• Backup e restauração
  • Executando um backup de chave completa
  • Executando uma restauração de chave completa

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Geral

Quando você interage com a biblioteca de Administração de Key Vault do Azure usando o SDK do .NET, os erros retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para solicitações de API REST.

Por exemplo, se você tentar recuperar uma atribuição de função que não existe no Key Vault do Azure, um 404 erro será retornado, indicando "Não Encontrado".

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

Configuração do registro em log do console

A maneira mais simples de ver os logs é habilitar o log do console. Para criar um ouvinte de log do SDK do Azure que gera mensagens para o console, use o AzureEventSourceListener.CreateConsoleLogger método .

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para saber mais sobre outros mecanismos de registro em log, confira aqui.

Próximas etapas

Comece agora com os nossos exemplos.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.