Partilhar via

Biblioteca de cliente chave do Azure Key Vault para .NET – versão 4.5.0

  • Artigo

O Azure Key Vault é um serviço cloud que fornece armazenamento seguro de chaves para encriptar os seus dados. Várias chaves e várias versões da mesma chave podem ser mantidas no Key Vault do Azure. As chaves criptográficas no Azure Key Vault são representadas como objetos JSON Web Key (JWK).

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.

O cliente da biblioteca de chaves de Key Vault do Azure suporta chaves RSA e chaves EC (Curva Elíptica), cada uma com suporte correspondente em módulos de segurança de hardware (HSM). Oferece operações para criar, obter, atualizar, eliminar, remover, fazer cópias de segurança, restaurar e listar as chaves e as respetivas versões.

Código fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do | produto Exemplos | Guia de migração

Introdução

Instalar o pacote

Instale a biblioteca de cliente de chaves do Azure Key Vault para .NET com NuGet:

dotnet add package Azure.Security.KeyVault.Keys

Pré-requisitos

Se estiver a criar um recurso de Key Vault padrão, execute o seguinte comando da CLI, substituindo <your-resource-group-name> e <your-key-vault-name> com os seus próprios nomes exclusivos:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Se estiver a 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 da classe KeyClient. 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 local e de produção que utilizam a autenticação de identidade gerida. 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

Esta secção só se aplica se estiver a criar um 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:

  • Mínimo de 3 pares de chaves RSA (máximo 10)
  • Especificar 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-key-vault-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

Criar KeyClient

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

// Create a new key client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new KeyClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new key using the key client.
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

// Retrieve a key using the key client.
key = client.GetKey("key-name");

Criar CryptographyClient

Depois de criar um KeyVaultKey no Azure Key Vault, também pode criar o CryptographyClient:

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
CryptographyClient cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

Conceitos-chave

KeyVaultKey

O Azure Key Vault suporta vários tipos e algoritmos de chave e permite a utilização de módulos de segurança de hardware (HSM) para chaves de valor elevado.

KeyClient

Existe KeyClient no SDK operações síncronas e assíncronas que permitem a seleção de um cliente com base no caso de utilização de uma aplicação. Depois de inicializar um KeyClient, pode interagir com os principais tipos de recursos no Azure Key Vault.

CryptographyClient

Existe CryptographyClient no SDK operações síncronas e assíncronas que permitem a seleção de um cliente com base no caso de utilização de uma aplicação. Depois de inicializar um CryptographyClient, pode utilizá-lo para realizar operações criptográficas com chaves armazenadas no Azure Key Vault.

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.Keys suporta APIs síncronas e assíncronas.

A secção seguinte fornece vários fragmentos de código com o clientcriado acima, abrangendo algumas das tarefas mais comuns relacionadas com o serviço de chaves do Azure Key Vault:

Exemplos de sincronização

Exemplos assíncronos

Criar uma chave

Crie uma chave a armazenar no Key Vault do Azure. Se já existir uma chave com o mesmo nome, é criada uma nova versão da chave.

// Create a key. Note that you can specify the type of key
// i.e. Elliptic curve, Hardware Elliptic Curve, RSA
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = client.CreateRsaKey(rsaCreateKey);

Console.WriteLine(rsaKey.Name);
Console.WriteLine(rsaKey.KeyType);

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = client.CreateEcKey(echsmkey);

Console.WriteLine(ecKey.Name);
Console.WriteLine(ecKey.KeyType);

Obter uma chave

GetKeyobtém uma chave armazenada anteriormente no Key Vault do Azure.

KeyVaultKey key = client.GetKey("key-name");

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

Atualizar uma chave existente

UpdateKeyPropertiesatualiza uma chave anteriormente armazenada no Key Vault do Azure.

KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

// You can specify additional application-specific metadata in the form of tags.
key.Properties.Tags["foo"] = "updated tag";

KeyVaultKey updatedKey = client.UpdateKeyProperties(key.Properties);

Console.WriteLine(updatedKey.Name);
Console.WriteLine(updatedKey.Properties.Version);
Console.WriteLine(updatedKey.Properties.UpdatedOn);

Eliminar uma chave

StartDeleteKeyinicia uma operação de execução prolongada para eliminar uma chave armazenada anteriormente no Key Vault do Azure. Pode obter a chave imediatamente sem esperar que a operação seja concluída. Quando a eliminação recuperável não está ativada para a Key Vault do Azure, esta operação elimina permanentemente a chave.

DeleteKeyOperation operation = client.StartDeleteKey("key-name");

DeletedKey key = operation.Value;
Console.WriteLine(key.Name);
Console.WriteLine(key.DeletedOn);

Eliminar e remover uma chave

Terá de aguardar que a operação de execução prolongada seja concluída antes de tentar remover ou recuperar a chave.

DeleteKeyOperation operation = client.StartDeleteKey("key-name");

// You only need to wait for completion if you want to purge or recover the key.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedKey key = operation.Value;
client.PurgeDeletedKey(key.Name);

Teclas de Lista

Este exemplo lista todas as chaves na Key Vault do Azure especificada.

Pageable<KeyProperties> allKeys = client.GetPropertiesOfKeys();

foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

Encriptar e Desencriptar

Este exemplo cria um CryptographyClient e utiliza-o para encriptar e desencriptar com uma chave no Azure Key Vault.

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
var cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

byte[] plaintext = Encoding.UTF8.GetBytes("A single block of plaintext");

// encrypt the data using the algorithm RSAOAEP
EncryptResult encryptResult = cryptoClient.Encrypt(EncryptionAlgorithm.RsaOaep, plaintext);

// decrypt the encrypted data.
DecryptResult decryptResult = cryptoClient.Decrypt(EncryptionAlgorithm.RsaOaep, encryptResult.Ciphertext);

Criar uma chave de forma assíncrona

As APIs assíncronas são idênticas às suas congéneres síncronas, mas devolvem com o sufixo "Assíncrono" típico para métodos assíncronos e devolvem uma Tarefa.

// Create a key of any type
KeyVaultKey key = await client.CreateKeyAsync("key-name", KeyType.Rsa);

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = await client.CreateRsaKeyAsync(rsaCreateKey);

Console.WriteLine(rsaKey.Name);
Console.WriteLine(rsaKey.KeyType);

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = await client.CreateEcKeyAsync(echsmkey);

Console.WriteLine(ecKey.Name);
Console.WriteLine(ecKey.KeyType);

Listar chaves de forma assíncrona

A listagem de chaves não depende de aguardar o GetPropertiesOfKeysAsync método, mas devolve uma AsyncPageable<KeyProperties> que pode utilizar com a await foreach instrução :

AsyncPageable<KeyProperties> allKeys = client.GetPropertiesOfKeysAsync();

await foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

Eliminar uma chave de forma assíncrona

Ao eliminar uma chave de forma assíncrona antes de a remover, pode aguardar o WaitForCompletionAsync método na operação. Por predefinição, este ciclo é ciclo indefinidamente, mas pode cancelá-lo ao transmitir um CancellationToken.

DeleteKeyOperation operation = await client.StartDeleteKeyAsync("key-name");

// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

DeletedKey key = operation.Value;
await client.PurgeDeletedKeyAsync(key.Name);

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 cliente chave do Azure Key Vault 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 chave que não existe no seu Key Vault do Azure, é devolvido um 404 erro que indica "Não Encontrado".

try
{
    KeyVaultKey key = client.GetKey("some_key");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Irá reparar que são registadas informações adicionais, como o ID do pedido de cliente da operação.

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"KeyNotFound","message":"Key not found: some_key"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

Passos seguintes

Estão disponíveis vários exemplos de biblioteca de cliente de chaves do Azure Key Vault neste repositório do GitHub. Estes exemplos fornecem código de exemplo para cenários adicionais normalmente encontrados ao trabalhar com o Azure Key Vault:

  • Sample1_HelloWorld.md – para trabalhar com o Azure Key Vault, incluindo:

    • Criar uma chave
    • Obter uma chave existente
    • Atualizar uma chave existente
    • Eliminar uma chave

  • Sample2_BackupAndRestore.md - Contém os fragmentos de código que funcionam com chaves de Key Vault do Azure, incluindo:

    • Criar cópias de segurança e recuperar uma chave

  • Sample3_GetKeys.md - Código de exemplo para trabalhar com chaves de Key Vault do Azure, incluindo:

    • Criar chaves
    • Listar todas as chaves no Key Vault
    • Atualizar chaves no Key Vault
    • Listar versões de uma chave especificada
    • Eliminar chaves do Key Vault
    • Listar chaves eliminadas no Key Vault

  • Sample4_EncryptDecrypt.md - Código de exemplo para realizar operações criptográficas com chaves de Key Vault do Azure, incluindo:

    • Encriptar e Desencriptar dados com o CryptographyClient

  • Sample5_SignVerify.md - Código de exemplo para trabalhar com chaves de Key Vault do Azure, incluindo:

    • Assinar um resumo pré-calculado e verificar a assinatura com Assinar e Verificar
    • Assinar dados não processados e verificar a assinatura com SignData e VerifyData

  • Sample6_WrapUnwrap.md - Código de exemplo para trabalhar com chaves de Key Vault do Azure, incluindo:

    • Moldar e Desembrulhar uma chave simétrica

Documentação Adicional

Contribuir

Veja o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para estas bibliotecas.

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.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

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