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

O Azure Key Vault é um serviço de nuvem que fornece armazenamento seguro de chaves para criptografar 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 JWK (Chave Web JSON).

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.

O cliente da biblioteca de chaves Key Vault do Azure dá suporte a chaves RSA e chaves EC (Curva Elíptica), cada uma com suporte correspondente em HSM (módulos de segurança de hardware). Ele oferece operações para criar, recuperar, atualizar, excluir, limpar, fazer backup, restaurar e listar as chaves e suas versões.

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

Introdução

Instalar o pacote

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

dotnet add package Azure.Security.KeyVault.Keys

Pré-requisitos

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

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

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

Se você estiver criando um recurso 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 da classe KeyClient. 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 utilizando a autenticação de identidade gerenciada. 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

Esta seção só se aplica se você estiver criando um 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:

• Pelo menos três pares de chave 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-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

Instancie um DefaultAzureCredential para passar para o cliente. 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.

// 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 Key Vault do Azure, você 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);

Principais conceitos

KeyVaultKey

O Azure Key Vault dá suporte a vários tipos de chave e algoritmos e permite o uso de HSM (módulos de segurança de hardware) para chaves de alto valor.

KeyClient

Existe um KeyClient que fornece operações síncronas e assíncronas no SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo. Depois de inicializar um KeyClient, você poderá interagir com os tipos de recursos primários no Azure Key Vault.

CryptographyClient

Existe um CryptographyClient que fornece operações síncronas e assíncronas no SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo. Depois de inicializar um CryptographyClient, você poderá usá-lo para executar operações criptográficas com chaves armazenadas no Azure Key Vault.

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.Keys dá suporte a APIs síncronas e assíncronas.

A seção a seguir fornece vários snippets de código usando o clientcriado acima, abrangendo algumas das tarefas mais comuns do Azure Key Vault principais tarefas relacionadas ao serviço:

Exemplos de sincronização

• Criar uma chave
• Recuperar uma chave
• Atualizar uma chave existente
• Excluir uma chave
• Excluir e limpar uma chave
• Listar chaves
• Criptografar e descriptografar

Exemplos assíncronos

• Criar uma chave de forma assíncrona
• Listar chaves de forma assíncrona
• Excluir uma chave de forma assíncrona

Criar uma chave

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

// 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);

Recuperar uma chave

GetKeyrecupera 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 armazenada anteriormente 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);

Excluir uma chave

StartDeleteKeyinicia uma operação de execução prolongada para excluir uma chave armazenada anteriormente no Key Vault do Azure. Você pode recuperar a chave imediatamente sem aguardar a conclusão da operação. Quando a exclusão reversível não está habilitada para o Key Vault do Azure, essa operação exclui permanentemente a chave.

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

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

Excluir e limpar uma chave

Você precisará aguardar a conclusão da operação de execução prolongada antes de tentar limpar 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);

Listar chaves

Este exemplo lista todas as chaves no Key Vault do Azure especificado.

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

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

Criptografar e descriptografar

Este exemplo cria um CryptographyClient e o usa para criptografar e descriptografar 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 aos seus equivalentes síncronos, mas retornam com o sufixo "Assíncrono" típico para métodos assíncronos e retornam 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

As chaves de listagem não dependem de aguardar o GetPropertiesOfKeysAsync método, mas retorna um AsyncPageable<KeyProperties> que você pode usar com a await foreach instrução :

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

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

Excluir uma chave de forma assíncrona

Ao excluir uma chave de forma assíncrona antes de purgá-la, você pode aguardar o WaitForCompletionAsync método na operação. Por padrão, isso executa um loop indefinidamente, mas você pode cancelá-lo passando 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);

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 clientes chave do Azure Key Vault usando o SDK do .NET, os erros retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para solicitações da API REST.

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

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

Você observará que informações adicionais são registradas, como a ID de solicitação do 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

Próximas etapas

Vários exemplos da biblioteca de clientes de chaves de Key Vault do Azure estão disponíveis neste repositório GitHub. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com o Azure Key Vault:

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

  • Criar uma chave
  • Obter uma chave existente
  • Atualizar uma chave existente
  • Excluir uma chave

• Sample2_BackupAndRestore.md – contém os snippets de código que funcionam com chaves de Key Vault do Azure, incluindo:

  • Fazer backup 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
  • Excluir chaves do Key Vault
  • Listar chaves excluídas no Key Vault

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

  • Criptografar e descriptografar 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 brutos 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:

  • Encapsular e desencapsular uma chave simétrica

Documentação Adicional

• Para obter uma documentação mais abrangente sobre o Azure Key Vault, consulte a documentação de referência da API.
• Para Biblioteca de clientes de segredos, consulte Biblioteca de clientes de segredos.
• Para Biblioteca de clientes de certificados, consulte Biblioteca de clientes de certificados.

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essas bibliotecas.

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.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

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.