Guida di avvio rapido: libreria client di HSM gestito di Azure Key Vault per .NET

Introduzione alla libreria client per .NET di Azure Key Vault Managed HSM. Il modulo di protezione hardware gestito è un servizio cloud completamente gestito, a disponibilità elevata, a tenant singolo e conforme agli standard che consente di proteggere le chiavi crittografiche per le applicazioni cloud, usando moduli di protezione hardware convalidati FIPS 140-3 di livello 3 . Per ulteriori informazioni sull'HSM gestito, consultare la Panoramica.

In questa guida introduttiva si apprenderà come accedere ed eseguire operazioni di crittografia sulle chiavi in un modulo di protezione hardware gestito usando la libreria client .NET.

Risorse della libreria client dell'HSM gestito:

documentazione di riferimento API | Codice sorgente della libreria | Package (NuGet)

Prerequisiti

Configurare l'ambiente locale

Questa guida introduttiva usa la libreria di identità Azure con interfaccia della riga di comando di Azure per eseguire l'autenticazione ai servizi di Azure. Gli sviluppatori possono anche usare Visual Studio o Visual Studio Code per autenticare le chiamate. Per altre informazioni, vedere Authenticate the client with Azure Identity client library.

Accedere a Azure

Eseguire il az login comando per accedere:

az login

Creare una nuova app console .NET

  1. In una shell dei comandi eseguire questo comando per creare un progetto denominato mhsm-console-app:

    dotnet new console --name mhsm-console-app

  2. Passare alla directory mhsm-console-app appena creata:

    cd mhsm-console-app

Installare i pacchetti

Installare le librerie client di identità di Azure e delle chiavi di Key Vault.

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

Creare il codice di esempio

Sostituire il contenuto di Program.cs con il codice seguente. Sostituisci <hsm-name> con il nome del tuo HSM gestito e <key-name> con un nome di chiave esistente.

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!");

Eseguire l'applicazione

Eseguire l'applicazione con il comando dotnet run:

dotnet run

L'output dovrebbe essere simile al seguente:

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!

Informazioni sul codice

Autenticazione con DefaultAzureCredential

DefaultAzureCredential seleziona automaticamente le credenziali appropriate in base all'ambiente:

Ambiente Credenziali usate
Funzioni, Servizio app e Macchine virtuali di Azure Identità gestita assegnata dal sistema o assegnata dall'utente
servizio Azure Kubernetes Identità del carico di lavoro
Sviluppo locale credenziali di interfaccia della riga di comando di Azure, Visual Studio o VS Code
Pipeline CI/CD Federazione o entità servizio dell'identità del carico di lavoro

La verifica delle credenziali controlla queste fonti in ordine:

  1. Variabili di ambiente
  2. Identità del carico di lavoro
  3. Identità gestita
  4. interfaccia della riga di comando di Azure
  5. Azure PowerShell
  6. credenziali di Visual Studio/VS Code

Per i carichi di lavoro di produzione in Azure, le identità gestite sono fortemente consigliate perché eliminano completamente la gestione delle credenziali.

Operazioni chiave

La KeyClient classe fornisce metodi per:

  • Creare, ottenere, aggiornare ed eliminare chiavi
  • Elencare le chiavi e le versioni delle chiavi
  • Eseguire il backup e il ripristino delle chiavi

La CryptographyClient classe fornisce operazioni di crittografia:

  • Crittografare e decrittografare i dati
  • Firmare e verificare le firme
  • Eseguire e annullare il wrapping delle chiavi

Assegnare ruoli di HSM gestito

Per consentire all'applicazione di accedere alle chiavi, assegnare il ruolo di Controllo degli accessi in base al ruolo locale di HSM gestito corretto alla propria identità gestita. Sostituire <vm-name>, <resource-group>e <hsm-name> con i valori effettivi.

# 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

Per altre informazioni su ruoli e autorizzazioni, vedere Ruoli predefiniti RBAC locali di HSM gestito.

Pulire le risorse

Quando non sono più necessari, eliminare il gruppo di risorse e tutte le risorse correlate:

az group delete --name <resource-group>

Avviso

L'eliminazione del gruppo di risorse attiva lo stato di eliminazione temporanea per il modulo di protezione hardware gestito. L'HSM gestito continua a essere fatturato fino a quando non viene eliminato definitivamente. Vedere Eliminazione temporanea e protezione dall'eliminazione dell'HSM gestito

Passaggi successivi

  • Last updated on