Início Rápido: Biblioteca cliente do HSM gerenciado do Azure Key Vault para .NET

Introdução à biblioteca de clientes do HSM gerenciado do Azure Key Vault para .NET. O HSM Gerenciado é um serviço de nuvem de gerenciamento completo, altamente disponível, de locatário único e compatível com padrões que permite proteger chaves criptográficas para seus aplicativos de nuvem, com HSMs validados pelo FIPS 140-3 Nível 3. Para obter mais informações sobre hsm gerenciado, examine a visão geral.

Neste início rápido, você aprenderá a acessar e executar operações criptográficas em chaves em um HSM Gerenciado usando a biblioteca de clientes .NET.

Recursos gerenciados da biblioteca de clientes HSM:

API reference documentation | Library source code | Package (NuGet)

Pré-requisitos

• Uma assinatura Azure. Criar um gratuitamente.
• Um HSM gerenciado provisionado e ativado. Consulte Quickstart: Provisionar e ativar um HSM gerenciado usando CLI do Azure.
• Uma chave criada no HSM Gerenciado. Consulte Gerenciar chaves em um HSM Gerenciado.
• Um recurso Azure com uma identidade gerenciada (como uma VM, Serviço de Aplicativo ou função Azure) ou CLI do Azure para desenvolvimento local.
• A identidade gerenciada deve ter a função RBAC local apropriada do HSM gerenciado atribuída. Confira o acesso seguro aos HSMs gerenciados.

• .NET 6 SDK ou posterior

Configurar o ambiente local

Este início rápido usa a biblioteca Azure Identity com CLI do Azure para se autenticar em serviços de Azure. Os desenvolvedores também podem usar Visual Studio ou Visual Studio Code para autenticar suas chamadas. Para obter mais informações, consulte Authenticate the client with Azure Identity client library.

Entrar no Azure

Execute o az login comando para entrar:

az login

Criar um novo aplicativo de console .NET

1. Em um shell de comando, execute o seguinte comando para criar um projeto chamado mhsm-console-app:

   dotnet new console --name mhsm-console-app
   

2. Altere para o diretório recém-criado mhsm-console-app:

   cd mhsm-console-app
   

Instalar os pacotes

Instale as bibliotecas de cliente Azure Identity e Key Vault Keys:

dotnet add package Azure.Identity
dotnet add package Azure.Security.KeyVault.Keys

Criar o código de exemplo

Substitua o conteúdo de Program.cs pelo código a seguir. Substitua <hsm-name> pelo nome do HSM Gerenciado e <key-name> por um nome de chave existente.

using Azure.Identity;
using Azure.Security.KeyVault.Keys;
using Azure.Security.KeyVault.Keys.Cryptography;

// Use DefaultAzureCredential for automatic credential selection
// Works with managed identities in Azure, and developer credentials locally
var credential = new DefaultAzureCredential();

// Connect to Managed HSM - replace with your HSM URI
var hsmUri = new Uri("https://<hsm-name>.managedhsm.azure.net");
var keyClient = new KeyClient(hsmUri, credential);

// Get a key reference
string keyName = "<key-name>";
Console.WriteLine($"Retrieving key '{keyName}' from Managed HSM...");
KeyVaultKey key = await keyClient.GetKeyAsync(keyName);
Console.WriteLine($"Key retrieved. Key type: {key.KeyType}");

// Perform cryptographic operations
var cryptoClient = new CryptographyClient(key.Id, credential);

// Encrypt data
byte[] plaintext = System.Text.Encoding.UTF8.GetBytes("Hello, Managed HSM!");
Console.WriteLine($"\nOriginal text: {System.Text.Encoding.UTF8.GetString(plaintext)}");

EncryptResult encryptResult = await cryptoClient.EncryptAsync(EncryptionAlgorithm.RsaOaep256, plaintext);
Console.WriteLine($"Encrypted (base64): {Convert.ToBase64String(encryptResult.Ciphertext)}");

// Decrypt data
DecryptResult decryptResult = await cryptoClient.DecryptAsync(EncryptionAlgorithm.RsaOaep256, encryptResult.Ciphertext);
Console.WriteLine($"Decrypted text: {System.Text.Encoding.UTF8.GetString(decryptResult.Plaintext)}");

Console.WriteLine("\nDone!");

Executar o aplicativo

Execute o aplicativo com o comando dotnet run:

dotnet run

Você deverá ver uma saída semelhante a:

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (base64): <encrypted-data>
Decrypted text: Hello, Managed HSM!

Done!

Compreender o código

Autenticação com DefaultAzureCredential

DefaultAzureCredential seleciona automaticamente a credencial apropriada com base em seu ambiente:

A credencial verifica essas fontes na ordem:

1. Variáveis de ambiente
2. Identidade da carga de trabalho
3. Identidade gerenciada
4. CLI do Azure
5. Azure PowerShell
6. credenciais de Visual Studio/VS Code

Para cargas de trabalho de produção em Azure, as identidades gerenciadas são altamente recomendadas porque eliminam totalmente o gerenciamento de credenciais.

Operações principais

A KeyClient classe fornece métodos para:

• Criar, obter, atualizar e excluir chaves
• Listar chaves e versões das chaves
• Chaves de backup e restauração

A CryptographyClient classe fornece operações criptográficas:

• Criptografar e descriptografar dados
• Assinar e verificar assinaturas
• Empacotar e desempacotar as chaves

Atribuir as funções do HSM gerenciado

Para que sua aplicação tenha acesso às chaves, atribua a função RBAC local apropriada do HSM gerenciado à sua identidade gerenciada. Substitua <vm-name>, <resource-group>e <hsm-name> com seus valores reais.

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name <hsm-name> \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

Para obter mais informações sobre as funções e as permissões, consulte Funções internas do RBAC local do HSM gerenciado.

Limpar os recursos

Quando não for mais necessário, exclua o grupo de recursos e todos os recursos relacionados:

az group delete --name <resource-group>

Próximas Etapas 

• Saiba mais sobre o acesso seguro aos HSMs gerenciados
• Configurar a rotação de chaves automatizada
• Examine as Melhores práticas do HSM Gerenciado
• Consulte Práticas recomendadas do HSM gerenciado