Schnellstart: Azure Key Vault Verwaltete HSM-Clientbibliothek für .NET

Erste Schritte mit der Azure Key Vault verwaltete HSM-Clientbibliothek für .NET. Verwaltetes HSM ist ein vollständig verwalteter, hochverwendiger, einzelinstanzenfähiger, standardkonformer Clouddienst, mit dem Sie kryptografische Schlüssel für Ihre Cloudanwendungen schützen können, wobei FIPS 140-3 Level 3 validierte HSMs verwendet werden. Weitere Informationen zu verwaltetem HSM erfahren Sie in der Übersicht.

In dieser Schnellstartanleitung erfahren Sie, wie Sie mithilfe der .NET Clientbibliothek auf Kryptografievorgänge auf Schlüssel in einem verwalteten HSM zugreifen und diese ausführen.

Verwaltete HSM-Clientbibliotheksressourcen:

API-Referenzdokumentation | Bibliotheksquellcode | Package (NuGet)

Voraussetzungen

• Ein Azure-Abonnement. Erstellen Sie ein kostenloses Konto.
• Ein bereitgestelltes und aktiviertes Managed HSM. Siehe Quickstart: Bereitstellen und Aktivieren eines verwalteten HSM mithilfe von Azure CLI.
• Ein Schlüssel, der in Ihrem verwalteten HSM erstellt wurde. Siehe Verwalten von Schlüsseln in einem verwalteten HSM.
• Eine Azure Ressource mit einer verwalteten Identität (z. B. einer VM, app Service oder Azure Funktion) oder Azure CLI für die lokale Entwicklung.
• Der verwalteten Identität muss die entsprechende lokale Managed HSM RBAC-Rolle zugewiesen sein. Siehe "Sicherer Zugriff auf Ihre verwalteten HSMs".

• .NET 6 SDK oder höher

Einrichten Ihrer lokalen Umgebung

In dieser Schnellstartanleitung wird die Azure Identitätsbibliothek mit Azure CLI verwendet, um sich bei Azure Diensten zu authentifizieren. Entwickler können auch Visual Studio oder Visual Studio Code verwenden, um ihre Anrufe zu authentifizieren. Weitere Informationen finden Sie unter Authenticate the client with Azure Identity client library.

Anmelden bei Azure

Führen Sie den az login Befehl aus, um sich anzumelden:

az login

Erstellen einer neuen .NET Konsolen-App

1. Führen Sie in einer Befehlsshell den folgenden Befehl aus, um ein Projekt namens mhsm-console-app zu erstellen:

   dotnet new console --name mhsm-console-app
   

2. Wechseln Zum neu erstellten mhsm-console-app-Verzeichnis :

   cd mhsm-console-app
   

Installieren der Pakete

Installieren Sie die Clientbibliotheken Azure Identity und Key Vault Keys:

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

Erstellen des Beispielcodes

Ersetzen Sie den Inhalt von Program.cs durch den folgenden Code. Ersetzen Sie <hsm-name> durch den Namen Ihres verwalteten HSM und <key-name> durch einen vorhandenen Schlüsselnamen.

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

Ausführen der Anwendung

Führen Sie die Anwendung mit Befehl dotnet run aus:

dotnet run

Eine ähnliche Ausgabe wie die folgende sollte angezeigt werden:

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!

Grundlegendes zum Code

Authentifizierung mit DefaultAzureCredential

DefaultAzureCredential wählt automatisch die passenden Zugangsdaten basierend auf Ihrer Umgebung aus.

Die Berechtigungsnachweise überprüfen diese Quellen in der folgenden Reihenfolge:

1. Umgebungsvariablen
2. Workload-Identität
3. Verwaltete Identität
4. Azure CLI
5. Azure PowerShell
6. Visual Studio/VS Code-Anmeldeinformationen

Für Produktionsworkloads in Azure werden verwaltete Identitäten dringend empfohlen, da sie die Verwaltung von Anmeldeinformationen vollständig beseitigen.

Wichtige Vorgänge

Die KeyClient Klasse bietet Methoden für:

• Erstellen, Abrufen, Aktualisieren und Löschen von Schlüsseln
• Liste Schlüssel und Schlüsselversionen
• Sichern und Wiederherstellen von Schlüsseln

Die CryptographyClient Klasse stellt kryptografische Vorgänge bereit:

• Verschlüsseln und Entschlüsseln von Daten
• Signieren und Überprüfen von Signaturen
• Schlüssel verpacken und auspacken

Zuweisen verwalteter HSM-Rollen

Damit Ihre Anwendung auf Zugriffsschlüssel zugreifen kann, weisen Sie Ihrer verwalteten Identität die entsprechende lokale RBAC-Rolle für Managed HSM zu. Ersetzen Sie <vm-name>, <resource-group> und <hsm-name> durch Ihre tatsächlichen Werte.

# 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

Weitere Informationen zu Rollen und Berechtigungen finden Sie unter Managed HSM local RBAC built-in roles.

Bereinigen von Ressourcen

Wenn sie nicht mehr benötigt wird, löschen Sie die Ressourcengruppe und alle zugehörigen Ressourcen:

az group delete --name <resource-group>

Nächste Schritte

• Informationen zum sicheren Zugriff auf Ihre verwalteten HSMs
• Konfigurieren der automatischen Schlüsseldrehung
• Sehen Sie sich die bewährten Methoden für verwaltetes HSM an.
• Informationen über integrierte lokale RBAC-Rollen von Managed HSM