Partilhar via

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

  • Artigo

O Azure Key Vault HSM Gerido é um serviço cloud totalmente gerido, altamente disponível e compatível com normas de inquilino único que lhe permite salvaguardar chaves criptográficas para as suas aplicações na cloud com HSMs validados fiPS 140-2 de Nível 3.

Os clientes da biblioteca de administração do Azure Key Vault suportam tarefas administrativas, como a cópia de segurança completa/restauro e o controlo de acesso baseado em funções (RBAC) ao nível da chave.

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

Introdução

Instalar o pacote

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

dotnet add package Azure.Security.KeyVault.Administration

Pré-requisitos

Para criar um recurso HSM Gerido, 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> , 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, terá de criar uma instância das classes de cliente abaixo. Precisa de um URL do cofre, que poderá ver como "Nome DNS" no portal e credenciais para instanciar um objeto de cliente.

Os exemplos mostrados abaixo utilizam um DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento e produção locais. Além disso, recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção. Pode encontrar mais informações sobre as diferentes formas de autenticação e os tipos de credenciais correspondentes na documentação da Identidade do Azure .

Para utilizar o DefaultAzureCredential fornecedor mostrado abaixo ou outros fornecedores de credenciais fornecidos com o SDK do Azure, primeiro tem de instalar o pacote Azure.Identity:

dotnet add package Azure.Identity

Ativar o HSM gerido

Todos os comandos do plano de dados são desativados até o HSM ser ativado. Não poderá criar chaves nem atribuir funções. Apenas os administradores designados que foram atribuídos durante o comando criar podem ativar o HSM. Para ativar o HSM, tem de transferir o domínio de segurança.

Para ativar o HSM, precisa de:

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

Para ativar o HSM, envia pelo menos 3 (no máximo 10) chaves públicas RSA para o HSM. O HSM encripta o domínio de segurança com estas chaves e envia-o de volta. Assim que este domínio de segurança for transferido com êxito, o HSM estará pronto para ser utilizado. Também tem de especificar o quórum, que é o número mínimo de chaves privadas necessárias para desencriptar o domínio de segurança.

O exemplo abaixo mostra como utilizar o openssl para gerar 3 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

Utilize o az keyvault security-domain download comando para transferir o domínio de segurança e ativar o HSM gerido. O exemplo abaixo utiliza 3 pares de chaves RSA (apenas são necessárias chaves públicas para este comando) e define o quórum 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

Controlar o acesso ao HSM gerido

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

Para efetuar outras ações em chaves, tem de atribuir principais a outras funções, como "Utilizador Criptografo do HSM Gerido", que pode realizar 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 melhores práticas para proteger corretamente o HSM gerido.

Criar KeyVaultAccessControlClient

Instanciar um DefaultAzureCredential para passar para o KeyVaultAccessControlClient. A mesma instância de uma credencial de token pode ser utilizada com vários clientes se estiverem a autenticar com a mesma identidade.

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

Criar KeyVaultBackupClient

Instanciar um DefaultAzureCredential para passar para o KeyVaultBackupClient. A mesma instância de uma credencial de token pode ser utilizada com vários clientes se estiverem a autenticar com a mesma identidade.

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

Criar KeyVaultSettingClient

Instanciar um DefaultAzureCredential para passar para o KeyVaultSettingsClient. A mesma instância de uma credencial de token pode ser utilizada com vários clientes se estiverem a autenticar com a mesma identidade.

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

Conceitos-chave

KeyVaultRoleDefinition

A KeyVaultRoleDefinition é uma coleção de permissões. Uma definição de função define as operações que podem ser executadas, como leitura, escrita e eliminação. Também pode definir as operações excluídas das operações permitidas.

As KeyVaultRoleDefinitions podem ser listadas e especificadas como parte de um KeyVaultRoleAssignment.

KeyVaultRoleAssignment

A KeyVaultRoleAssignment é a associação de uma KeyVaultRoleDefinition a um principal de serviço. Podem ser criados, listados, obtidos individualmente e eliminados.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient fornece operações síncronas e assíncronas que permitem a gestão de KeyVaultRoleDefinition objetos e KeyVaultRoleAssignment .

KeyVaultBackupClient

A KeyVaultBackupClient fornece operações síncronas e assíncronas para realizar cópias de segurança de chaves completas, restauros de chaves completos e restauros de chaves seletivos.

BackupOperation

A BackupOperation representa uma operação de execução prolongada para uma cópia de segurança de chave completa.

RestoreOperation

A RestoreOperation representa uma operação de execução prolongada para um restauro de chave completa e seletiva.

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Opções de | cliente Aceder à resposta | Operações de execução prolongada | Lidar com falhas | Diagnósticos | A gozar | Duração do cliente

Exemplos

O pacote Azure.Security.KeyVault.Administration suporta APIs síncronas e assíncronas.

A secção seguinte fornece vários fragmentos de código que utilizam o client criado acima para o controlo de acesso ou clientes de cópia de segurança, abrangendo algumas das tarefas relacionadas com o controlo de acesso do Azure Key Vault mais comuns:

Exemplos de sincronização

Exemplos assíncronos

Resolução de problemas

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

Geral

Quando interage com a biblioteca de Administração Key Vault do Azure com o SDK .NET, os erros devolvidos pelo serviço correspondem aos mesmos códigos de estado HTTP devolvidos para pedidos de API REST.

Por exemplo, se tentar obter uma atribuição de função que não existe no seu Key Vault do Azure, é devolvido um 404 erro que indica "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

Configurar o registo da consola

A forma mais simples de ver os registos é ativar o registo da consola. Para criar um serviço de escuta de registos do SDK do Azure que produz mensagens para a consola, utilize o AzureEventSourceListener.CreateConsoleLogger método .

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

Para saber mais sobre outros mecanismos de registo, veja aqui.

Passos seguintes

Comece a utilizar os nossos exemplos.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões