Clientbibliothek für die Azure KeyVault-Verwaltung für .NET– Version 4.3.0

Azure Key Vault Managed HSM ist ein vollständig verwalteter, hochverfügbarer, standardkonformer Clouddienst mit nur einem Mandanten, mit dem Sie kryptografische Schlüssel für Ihre Cloudanwendungen mit FIPS 140-2 Level 3-validierten HSMs schützen können.

Die Clients der Azure Key Vault-Verwaltungsbibliothek unterstützen administrative Aufgaben wie vollständige Sicherung/Wiederherstellung und rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) auf Schlüsselebene.

Quellcode | Paket (NuGet) | Produktdokumentation | Proben

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Key Vault-Verwaltungsclientbibliothek für .NET mit NuGet:

dotnet add package Azure.Security.KeyVault.Administration

Voraussetzungen

• Ein Azure-Abonnement.
• Eine vorhandene Azure Key Vault. Wenn Sie eine Azure Key Vault erstellen müssen, können Sie die Azure CLI verwenden.
• Autorisierung für eine vorhandene Azure-Key Vault entweder mithilfe der RBAC (empfohlen) oder der Zugriffssteuerung.

Führen Sie den folgenden CLI-Befehl aus, um eine verwaltete HSM-Ressource zu erstellen:

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

Zum Abrufen <your-user-object-id> können Sie den folgenden CLI-Befehl ausführen:

az ad user show --id <your-user-principal> --query id

Authentifizieren des Clients

Um mit dem Azure Key Vault-Dienst zu interagieren, müssen Sie eine instance der folgenden Clientklassen erstellen. Sie benötigen eine Tresor-URL, die im Portal möglicherweise als "DNS-Name" angezeigt wird, und Anmeldeinformationen, um ein Clientobjekt zu instanziieren.

In den unten gezeigten Beispielen wird ein DefaultAzureCredentialverwendet, das für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Darüber hinaus wird empfohlen, eine verwaltete Identität für die Authentifizierung in Produktionsumgebungen zu verwenden. Weitere Informationen zu verschiedenen Authentifizierungsmethoden und den entsprechenden Anmeldeinformationstypen finden Sie in der Dokumentation zu Azure Identity .

Um den DefaultAzureCredential unten gezeigten Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, müssen Sie zuerst das Azure.Identity-Paket installieren:

dotnet add package Azure.Identity

Aktivieren Ihres verwalteten HSM

Bis zur Aktivierung des HSM sind alle Datenebenenbefehle deaktiviert. Sie können keine Schlüssel erstellen oder Rollen zuweisen. Nur die designierten Administratoren, die im Rahmen des Erstellungsbefehls zugewiesen wurden, können das HSM aktivieren. Zum Aktivieren des HSM müssen Sie die Sicherheitsdomäne herunterladen.

Für die HSM-Aktivierung benötigen Sie Folgendes:

• Mindestens 3 RSA-Schlüsselpaare (maximal 10)
• Geben Sie die Mindestanzahl von Schlüsseln an, die zum Entschlüsseln der Sicherheitsdomäne (Quorum) erforderlich sind.

Für die HSM-Aktivierung müssen zwischen drei und zehn öffentliche RSA-Schlüssel an das HSM gesendet werden. Das HSM verschlüsselt die Sicherheitsdomäne mit diesen Schlüsseln und sendet sie zurück. Nachdem diese Sicherheitsdomäne erfolgreich heruntergeladen wurde, ist Ihr HSM einsatzbereit. Darüber hinaus müssen Sie ein Quorum angeben. Hierbei handelt es sich um die Mindestanzahl privater Schlüssel, die zum Entschlüsseln der Sicherheitsdomäne erforderlich sind.

Das folgende Beispiel zeigt, wie Sie mit openssl 3 selbstsignierte Zertifikate generieren.

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

Verwenden Sie den Befehl az keyvault security-domain download, um die Sicherheitsdomäne herunterzuladen und Ihr verwaltetes HSM zu aktivieren. Im folgenden Beispiel werden drei RSA-Schlüsselpaare verwendet (für diesen Befehl sind nur öffentliche Schlüssel erforderlich) und das Quorum auf 2 festgelegt.

az keyvault security-domain download --hsm-name <your-managed-hsm-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

Steuern des Zugriffs auf Ihr verwaltetes HSM

Die während der Erstellung zugewiesenen Administratoren werden automatisch der integrierten Rolle "Verwaltete HSM-Administratoren" hinzugefügt, die neben anderen eingeschränkten Berechtigungen eine Sicherheitsdomäne herunterladen und Rollen für den Zugriff auf Datenebene verwalten können.

Um andere Aktionen für Schlüssel auszuführen, müssen Sie Prinzipale anderen Rollen zuweisen, z. B. "Managed HSM Crypto User", die nicht destruktive Schlüsselvorgänge ausführen können:

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

Lesen Sie bewährte Methoden zum ordnungsgemäßen Schützen Ihres verwalteten HSM.

Erstellen von KeyVaultAccessControlClient

Instanziieren Sie ein DefaultAzureCredential , um an das KeyVaultAccessControlClientzu übergeben. Die gleiche instance einer Tokenanmeldeinformation kann mit mehreren Clients verwendet werden, wenn sie sich mit derselben Identität authentifizieren.

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Erstellen von KeyVaultBackupClient

Instanziieren Sie ein DefaultAzureCredential , um an das KeyVaultBackupClientzu übergeben. Die gleiche instance einer Tokenanmeldeinformation kann mit mehreren Clients verwendet werden, wenn sie sich mit derselben Identität authentifizieren.

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Erstellen von KeyVaultSettingClient

Instanziieren Sie ein DefaultAzureCredential , um an das KeyVaultSettingsClientzu übergeben. Die gleiche instance einer Tokenanmeldeinformation kann mit mehreren Clients verwendet werden, wenn sie sich mit derselben Identität authentifizieren.

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Wichtige Begriffe

KeyVaultRoleDefinition

Ein KeyVaultRoleDefinition ist eine Sammlung von Berechtigungen. Eine Rollendefinition definiert die Vorgänge, die ausgeführt werden können, z. B. Lesen, Schreiben und Löschen. Es kann auch die Vorgänge definieren, die von zulässigen Vorgängen ausgeschlossen sind.

KeyVaultRoleDefinitions können aufgelistet und als Teil eines KeyVaultRoleAssignmentangegeben werden.

KeyVaultRoleAssignment

Ein KeyVaultRoleAssignment ist die Zuordnung einer KeyVaultRoleDefinition zu einem Dienstprinzipal. Sie können erstellt, aufgelistet, einzeln abgerufen und gelöscht werden.

KeyVaultAccessControlClient

Ein KeyVaultAccessControlClient bietet sowohl synchrone als auch asynchrone Vorgänge, die die Verwaltung von KeyVaultRoleDefinition - und KeyVaultRoleAssignment -Objekten ermöglichen.

KeyVaultBackupClient

Ein KeyVaultBackupClient bietet sowohl synchrone als auch asynchrone Vorgänge für vollständige Schlüsselsicherungen, Vollständige Schlüsselwiederherstellungen und selektive Schlüsselwiederherstellungen.

BackupOperation

Ein BackupOperation stellt einen lang andauernden Vorgang für eine vollständige Schlüsselsicherung dar.

RestoreOperation

Ein RestoreOperation stellt einen vorgang mit langer Ausführungsdauer sowohl für die Wiederherstellung des vollständigen Schlüssels als auch für die selektive Schlüsselwiederherstellung dar.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und voneinander unabhängig sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Das Azure.Security.KeyVault.Administration-Paket unterstützt synchrone und asynchrone APIs.

Der folgende Abschnitt enthält mehrere Codeausschnitte, die das client oben für Zugriffssteuerungs- oder Sicherungsclients erstellte verwenden. Dabei werden einige der häufigsten Aufgaben im Zusammenhang mit der Zugriffssteuerung in Azure Key Vault behandelt:

Synchronisierungsbeispiele

• Zugriffssteuerung
  • Auflisten aller Rollendefinitionen
  • Auflisten aller Rollenzuweisungen
  • Erstellen einer Rollenzuweisung
  • Abrufen einer Rollenzuweisung
  • Löschen einer Rollenzuweisung
• Sichern und Wiederherstellen
  • Ausführen einer vollständigen Schlüsselsicherung
  • Ausführen einer Vollständigen Schlüsselwiederherstellung

Asynchrone Beispiele

• Zugriffssteuerung
  • Auflisten aller Rollendefinitionen
  • Auflisten aller Rollenzuweisungen
  • Erstellen einer Rollenzuweisung
  • Abrufen einer Rollenzuweisung
  • Löschen einer Rollenzuweisung
• Sichern und Wiederherstellen
  • Ausführen einer vollständigen Schlüsselsicherung
  • Ausführen einer Vollständigen Schlüsselwiederherstellung

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Allgemein

Wenn Sie mit der Azure Key Vault-Verwaltungsbibliothek mithilfe des .NET SDK interagieren, entsprechen vom Dienst zurückgegebene Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise versuchen, eine Rollenzuweisung abzurufen, die in Ihrem Azure-Key Vault nicht vorhanden ist, wird ein 404 Fehler zurückgegeben, der auf "Nicht gefunden" hinweist.

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

Einrichten der Konsolenprotokollierung

Die einfachste Möglichkeit, die Protokolle anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren. Verwenden Sie die -Methode, um einen Azure SDK-Protokolllistener zu erstellen, der Nachrichten an die AzureEventSourceListener.CreateConsoleLogger Konsole ausgibt.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Weitere Informationen zu anderen Protokollierungsmechanismen finden Sie hier.

Nächste Schritte

Erste Schritte mit den Beispielen

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.