Azure Key Vault Schlüsselclientbibliothek für .NET – Version 4.5.0

Azure Key Vault ist ein Clouddienst, der eine sichere Speicherung von Schlüsseln zum Verschlüsseln Ihrer Daten ermöglicht. Mehrere Schlüssel und mehrere Versionen desselben Schlüssels können im Azure-Key Vault beibehalten werden. Kryptografische Schlüssel in Azure Key Vault werden als JSON-Webschlüssel (JWK)-Objekte dargestellt.

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

Der Azure Key Vault-Schlüsselbibliotheksclient unterstützt RSA-Schlüssel und EC-Schlüssel (Elliptic Curve), die jeweils in Hardwaresicherheitsmodulen (HSM) unterstützt werden. Es bietet Vorgänge zum Erstellen, Abrufen, Aktualisieren, Löschen, Löschen, Sichern, Wiederherstellen und Auflisten der Schlüssel und ihrer Versionen.

Quellcode | Paket (NuGet) | API-Referenzdokumentation | Produktdokumentation | Proben | Migrationshandbuch

Erste Schritte

Installieren des Pakets

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

dotnet add package Azure.Security.KeyVault.Keys

Voraussetzungen

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

Wenn Sie eine Standardressource Key Vault erstellen, führen Sie den folgenden CLI-Befehl aus, um und <your-key-vault-name> durch Ihre eigenen eindeutigen <your-resource-group-name> Namen zu ersetzen:

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

Wenn Sie eine verwaltete HSM-Ressource erstellen, führen Sie den folgenden CLI-Befehl aus:

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 KeyClient-Klasse erstellen. Sie benötigen eine Tresor-URL, die möglicherweise als "DNS-Name" im Portal angezeigt wird, und Anmeldeinformationen zum Instanziieren eines Clientobjekts.

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

Um den unten gezeigten DefaultAzureCredential Anbieter oder andere Anbieter von Anmeldeinformationen 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

Dieser Abschnitt gilt nur, wenn Sie ein verwaltetes HSM erstellen. 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 drei RSA-Schlüsselpaare (maximal zehn)
• Geben Sie die Mindestanzahl von Schlüsseln an, die zum Entschlüsseln der Sicherheitsdomäne erforderlich sind (Quorum).

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.

Im folgenden Beispiel wird gezeigt, 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 3 RSA-Schlüsselpaare verwendet (für diesen Befehl werden nur öffentliche Schlüssel benötigt) und das Quorum auf 2 festgelegt.

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

KeyClient erstellen

Instanziieren Sie eine DefaultAzureCredential instanziieren, um an den Client zu übergeben. Die gleichen instance eines Tokenanmeldeinformationen können mit mehreren Clients verwendet werden, wenn sie sich mit derselben Identität authentifizieren.

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

Erstellen von CryptographyClient

Nachdem Sie einen KeyVaultKey im Azure-Key Vault erstellt haben, können Sie auch den CryptographyClient erstellen:

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

Wichtige Begriffe

KeyVaultKey

Azure Key Vault unterstützt mehrere Schlüsseltypen und Algorithmen und ermöglicht die Verwendung von Hardwaresicherheitsmodulen (HSM) für hochwertige Schlüssel.

KeyClient

Im KeyClient SDK ist eine sowohl synchrone als auch asynchrone Vorgänge vorhanden, die die Auswahl eines Clients basierend auf dem Anwendungsfall ermöglichen. Nachdem Sie ein KeyClientinitialisiert haben, können Sie mit den primären Ressourcentypen in Azure Key Vault interagieren.

CryptographyClient

Im CryptographyClient SDK ist eine sowohl synchrone als auch asynchrone Vorgänge vorhanden, die die Auswahl eines Clients basierend auf dem Anwendungsfall ermöglichen. Nachdem Sie einen CryptographyClientinitialisiert haben, können Sie es verwenden, um kryptografische Vorgänge mit schlüsseln auszuführen, die in Azure Key Vault gespeichert sind.

Threadsicherheit

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

Zusätzliche Konzepte

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

Beispiele

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

Der folgende Abschnitt enthält mehrere Codeausschnitte unter Verwendung des clientoben erstellten, die einige der häufigsten Azure Key Vault wichtigsten Dienstaufgaben behandeln:

Synchronisierungsbeispiele

• Erstellen eines Schlüssels
• Abrufen eines Schlüssels
• Aktualisieren eines vorhandenen Schlüssels
• Löschen eines Schlüssels
• Löschen und Löschen eines Schlüssels
• Auflisten von Schlüsseln
• Verschlüsseln und Entschlüsseln

Asynchrone Beispiele

• asynchrones Erstellen eines Schlüssels
• Asynchrones Auflisten von Schlüsseln
• asynchrones Löschen eines Schlüssels

Erstellen eines Schlüssels

Erstellen Sie einen Schlüssel, der im Azure-Key Vault gespeichert werden soll. Wenn bereits ein Schlüssel mit demselben Namen vorhanden ist, wird eine neue Version des Schlüssels erstellt.

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

Abrufen eines Schlüssels

GetKeyruft einen Schlüssel ab, der zuvor im Azure-Key Vault gespeichert wurde.

KeyVaultKey key = client.GetKey("key-name");

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

Aktualisieren eines vorhandenen Schlüssels

UpdateKeyPropertiesaktualisiert einen Schlüssel, der zuvor im Azure-Key Vault gespeichert wurde.

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

Löschen eines Schlüssels

StartDeleteKeystartet einen Vorgang mit langer Ausführungsdauer, um einen Schlüssel zu löschen, der zuvor im Azure-Key Vault gespeichert wurde. Sie können den Schlüssel sofort abrufen, ohne auf den Abschluss des Vorgangs zu warten. Wenn vorläufiges Löschen für die Azure-Key Vault nicht aktiviert ist, löscht dieser Vorgang den Schlüssel endgültig.

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

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

Löschen und Löschen eines Schlüssels

Sie müssen warten, bis der Vorgang mit langer Ausführung abgeschlossen ist, bevor Sie versuchen, den Schlüssel zu bereinigen oder wiederherzustellen.

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

Dient zum Auflisten von Schlüsseln.

In diesem Beispiel werden alle Schlüssel im angegebenen Azure-Key Vault aufgelistet.

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

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

Verschlüsseln und Entschlüsseln

In diesem Beispiel wird ein CryptographyClient erstellt und zum Verschlüsseln und Entschlüsseln mit einem Schlüssel in Azure Key Vault verwendet.

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

asynchrones Erstellen eines Schlüssels

Die asynchronen APIs sind mit ihren synchronen Gegenstücken identisch, geben jedoch mit dem typischen Suffix "Asynchron" für asynchrone Methoden zurück und geben einen Task zurück.

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

Asynchrones Auflisten von Schlüsseln

Das Auflisten von Schlüsseln basiert nicht auf dem Warten der GetPropertiesOfKeysAsync -Methode, sondern gibt eine AsyncPageable<KeyProperties> zurück, die Sie mit der await foreach -Anweisung verwenden können:

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

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

asynchrones Löschen eines Schlüssels

Wenn Sie einen Schlüssel asynchron löschen, bevor Sie ihn löschen, können Sie die WaitForCompletionAsync -Methode für den Vorgang abwarten. Standardmäßig wird diese Schleife auf unbestimmte Zeit ausgeführt, aber Sie können sie abbrechen, indem Sie einen CancellationTokenübergeben.

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

Problembehandlung

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

Allgemein

Wenn Sie mit der Azure Key Vault Schlüsselclientbibliothek 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, einen Schlüssel abzurufen, der in Ihrer Azure-Key Vault nicht vorhanden ist, wird ein 404 Fehler zurückgegeben, der auf "Nicht gefunden" hinweist.

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

Sie werden feststellen, dass zusätzliche Informationen protokolliert werden, z. B. die Clientanforderungs-ID des Vorgangs.

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

Nächste Schritte

In diesem GitHub-Repository stehen Ihnen mehrere Beispiele für die Clientbibliothek von Azure Key Vault Schlüsseln zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Azure Key Vault auftreten:

• Sample1_HelloWorld.md– für die Arbeit mit Azure Key Vault, einschließlich:

  • Erstellen eines Schlüssels
  • Abrufen eines vorhandenen Schlüssels
  • Aktualisieren eines vorhandenen Schlüssels
  • Löschen eines Schlüssels

• Sample2_BackupAndRestore.md: Enthält die Codeausschnitte, die mit Azure Key Vault-Schlüsseln arbeiten, einschließlich:

  • Sichern und Wiederherstellen eines Schlüssels

• Sample3_GetKeys.md : Beispielcode für die Arbeit mit Azure Key Vault-Schlüsseln, einschließlich:

  • Erstellen von Schlüsseln
  • Auflisten aller Schlüssel im Key Vault
  • Aktualisieren von Schlüsseln im Key Vault
  • Auflisten von Versionen eines angegebenen Schlüssels
  • Löschen von Schlüsseln aus dem Key Vault
  • Auflisten gelöschter Schlüssel im Key Vault

• Sample4_EncryptDecrypt.md: Beispielcode zum Ausführen kryptografischer Vorgänge mit Azure Key Vault-Schlüsseln, einschließlich:

  • Verschlüsseln und Entschlüsseln von Daten mit dem CryptographyClient

• Sample5_SignVerify.md : Beispielcode für die Arbeit mit Azure Key Vault-Schlüsseln, einschließlich:

  • Signieren eines vorab berechneten Digests und Überprüfen der Signatur mit Sign and Verify
  • Signieren von Rohdaten und Überprüfen der Signatur mit SignData und VerifyData

• Sample6_WrapUnwrap.md: Beispielcode für die Arbeit mit Azure Key Vault-Schlüsseln, einschließlich:

  • Umschließen und Entpacken eines symmetrischen Schlüssels

Zusätzliche Dokumentation

• Eine ausführlichere Dokumentation zu Azure Key Vault finden Sie in der API-Referenzdokumentation.
• Informationen zur Geheimen Clientbibliothek finden Sie unter Geheimnisclientbibliothek.
• Informationen zur Zertifikatclientbibliothek finden Sie unter Zertifikatclientbibliothek.

Mitwirken

Ausführliche Informationen zum Erstellen, Testen und Mitwirken zu diesen Bibliotheken finden Sie im CONTRIBUTING.md .

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.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

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.