Azure Key Vault-clientbibliotheek voor sleutels voor .NET - versie 4.5.0

Azure Key Vault is een cloudservice die beveiligde opslag van sleutels biedt voor het versleutelen van uw gegevens. Meerdere sleutels en meerdere versies van dezelfde sleutel kunnen worden bewaard in de Azure Key Vault. Cryptografische sleutels in Azure Key Vault worden weergegeven als JWK-objecten (JSON Web Key).

Azure Key Vault Managed HSM is een volledig beheerde, maximaal beschikbare cloudservice die voldoet aan standaarden met één tenant, waarmee u cryptografische sleutels voor uw cloudtoepassingen kunt beveiligen met behulp van HSM's met FIPS 140-2 Niveau 3.

De Azure Key Vault-sleutelbibliotheekclient ondersteunt RSA-sleutels en EC-sleutels (Elliptic Curve), elk met bijbehorende ondersteuning in hardwarebeveiligingsmodules (HSM). Het biedt bewerkingen voor het maken, ophalen, bijwerken, verwijderen, opschonen, back-up maken, herstellen en vermelden van de sleutels en de bijbehorende versies.

Broncode | Pakket (NuGet) | API-referentiedocumentatie | Productdocumentatie | Monsters | Migratiehandleiding

Aan de slag

Het pakket installeren

Installeer de clientbibliotheek voor Azure Key Vault-sleutels voor .NET met NuGet:

dotnet add package Azure.Security.KeyVault.Keys

Vereisten

• Een Azure-abonnement.
• Een bestaande Azure-Key Vault. Als u een Azure-Key Vault wilt maken, kunt u Azure Portal of Azure CLI gebruiken.
• Autorisatie voor een bestaande Azure-Key Vault met behulp van RBAC (aanbevolen) of toegangsbeheer.

Als u een standaardresource Key Vault maakt, voert u de volgende CLI-opdracht uit om en <your-key-vault-name> te <your-resource-group-name> vervangen door uw eigen, unieke namen:

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

Als u een beheerde HSM-resource maakt, voert u de volgende CLI-opdracht uit:

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

<your-user-object-id> U kunt de volgende CLI-opdracht uitvoeren:

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

De client verifiëren

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de klasse KeyClient maken. U hebt een kluis-URL nodig, die u mogelijk ziet als 'DNS-naam' in de portal, en referenties om een clientobject te instantiëren.

In de onderstaande voorbeelden wordt een DefaultAzureCredentialgebruikt. Dit is geschikt voor de meeste scenario's, waaronder lokale ontwikkel- en productieomgevingen die gebruikmaken van verificatie van beheerde identiteiten. Daarnaast raden we u aan een beheerde identiteit te gebruiken voor verificatie in productieomgevingen. Meer informatie over verschillende manieren om te verifiëren en de bijbehorende referentietypen vindt u in de Documentatie voor Azure Identity .

Als u de DefaultAzureCredential onderstaande provider of andere referentieproviders wilt gebruiken die bij de Azure SDK worden geleverd, moet u eerst het pakket Azure.Identity installeren:

dotnet add package Azure.Identity

Uw beheerde HSM activeren

Deze sectie is alleen van toepassing als u een beheerde HSM maakt. Alle gegevensvlakopdrachten worden uitgeschakeld totdat de HSM is geactiveerd. U kunt geen sleutels maken of rollen toewijzen. Alleen de aangewezen beheerders, die zijn toegewezen tijdens het maken van de opdracht, kunnen de HSM activeren. Als u de HSM wilt activeren, moet u het beveiligingsdomein downloaden.

Om uw HSM te activeren, hebt u het volgende nodig:

• Minimaal 3 RSA-sleutelparen (maximaal 10)
• Geef het minimum aantal sleutels op dat vereist is voor het ontsleutelen van het beveiligingsdomein (quorum)

Als u de HSM wilt activeren, stuurt u ten minste 3 (maximaal 10) openbare RSA-sleutels naar de HSM. De HSM versleutelt het beveiligingsdomein met deze sleutels en stuurt het terug. Zodra dit beveiligingsdomein is gedownload, is uw HSM klaar voor gebruik. U moet ook een quorum opgeven. Dit is het minimale aantal persoonlijke sleutels dat vereist is voor het ontsleutelen van het beveiligingsdomein.

In het onderstaande voorbeeld ziet u hoe u openssl gebruikt om 3 zelfondertekende certificaten te genereren.

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

Gebruik de az keyvault security-domain download opdracht om het beveiligingsdomein te downloaden en uw beheerde HSM te activeren. In het onderstaande voorbeeld worden 3 RSA-sleutelparen gebruikt (voor deze opdracht zijn alleen openbare sleutels nodig) en wordt het quorum ingesteld op 2.

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 maken

Instantieer een DefaultAzureCredential om door te geven aan de client. Hetzelfde exemplaar van een tokenreferentie kan worden gebruikt met meerdere clients als ze verifiëren met dezelfde identiteit.

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

Cryptografieclient maken

Nadat u een KeyVaultKey hebt gemaakt in de Azure Key Vault, kunt u ook de CryptographyClient maken:

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

Belangrijkste concepten

KeyVaultKey

Azure Key Vault ondersteunt meerdere sleuteltypen en algoritmen en maakt het gebruik van hardwarebeveiligingsmodules (HSM) voor sleutels met hoge waarde mogelijk.

KeyClient

Er bestaat een KeyClient die zowel synchrone als asynchrone bewerkingen biedt in de SDK, zodat een client kan worden geselecteerd op basis van de use-case van een toepassing. Nadat u een KeyClienthebt geïnitialiseerd, kunt u werken met de primaire resourcetypen in Azure Key Vault.

CryptographyClient

Er bestaat een CryptographyClient die zowel synchrone als asynchrone bewerkingen biedt in de SDK, zodat een client kan worden geselecteerd op basis van de use-case van een toepassing. Nadat u een CryptographyClienthebt geïnitialiseerd, kunt u deze gebruiken om cryptografische bewerkingen uit te voeren met sleutels die zijn opgeslagen in Azure Key Vault.

Veiligheid van schroefdraad

We garanderen dat alle clientexemplaren veilig zijn en onafhankelijk van elkaar zijn (richtlijn). Dit zorgt ervoor dat de aanbeveling om clientexemplaren opnieuw te gebruiken altijd veilig is, zelfs voor alle threads.

Aanvullende concepten

Clientopties | Toegang tot het antwoord | Langlopende bewerkingen | Fouten | afhandelen Diagnostics | Spottende | Clientlevensduur

Voorbeelden

Het pakket Azure.Security.KeyVault.Keys ondersteunt synchrone en asynchrone API's.

De volgende sectie bevat verschillende codefragmenten met behulp van de clienthierboven gemaakte code voor enkele van de meest voorkomende azure Key Vault belangrijke service-gerelateerde taken:

Voorbeelden van synchronisatie

• Een sleutel maken
• Een sleutel ophalen
• Een bestaande sleutel bijwerken
• Een sleutel verwijderen
• Een sleutel verwijderen en opschonen
• Sleutels vermelden
• Versleutelen en ontsleutelen

Asynchrone voorbeelden

• Asynchroon een sleutel maken
• Sleutels asynchroon weergeven
• Een sleutel asynchroon verwijderen

Een sleutel maken

Maak een sleutel die moet worden opgeslagen in de Azure Key Vault. Als er al een sleutel met dezelfde naam bestaat, wordt er een nieuwe versie van de sleutel gemaakt.

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

Een sleutel ophalen

GetKeyhaalt een sleutel op die eerder is opgeslagen in de Azure Key Vault.

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

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

Een bestaande sleutel bijwerken

UpdateKeyPropertieswerkt een sleutel bij die eerder is opgeslagen in de Azure Key Vault.

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

Een sleutel verwijderen

StartDeleteKeystart een langdurige bewerking om een sleutel te verwijderen die eerder is opgeslagen in de Azure Key Vault. U kunt de sleutel onmiddellijk ophalen zonder te wachten tot de bewerking is voltooid. Wanneer voorlopig verwijderen niet is ingeschakeld voor de Azure Key Vault, wordt de sleutel met deze bewerking definitief verwijderd.

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

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

Een sleutel verwijderen en opschonen

U moet wachten tot de langlopende bewerking is voltooid voordat u probeert de sleutel te verwijderen of te herstellen.

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

Lijstsleutels

In dit voorbeeld worden alle sleutels in de opgegeven Azure Key Vault weergegeven.

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

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

Versleutelen en ontsleutelen

In dit voorbeeld wordt een CryptographyClient gemaakt en gebruikt om deze te versleutelen en ontsleutelen met een sleutel in Azure Key Vault.

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

Asynchroon een sleutel maken

De asynchrone API's zijn identiek aan hun synchrone tegenhangers, maar worden geretourneerd met het typische 'Asynchrone' achtervoegsel voor asynchrone methoden en retourneren een taak.

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

Sleutels asynchroon weergeven

Het weergeven van sleutels is niet afhankelijk van het wachten op de GetPropertiesOfKeysAsync methode, maar retourneert een AsyncPageable<KeyProperties> die u kunt gebruiken met de await foreach -instructie:

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

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

Een sleutel asynchroon verwijderen

Wanneer u een sleutel asynchroon verwijdert voordat u deze opschoont, kunt u wachten op de WaitForCompletionAsync methode voor de bewerking. Standaard wordt deze lussen voor onbepaalde tijd uitgevoerd, maar u kunt deze annuleren door een CancellationTokendoor te geven.

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

Problemen oplossen

Zie onze gids voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.

Algemeen

Wanneer u communiceert met de Azure Key Vault-clientbibliotheek met behulp van de .NET SDK, komen fouten die door de service worden geretourneerd, overeen met dezelfde HTTP-statuscodes die worden geretourneerd voor REST API-aanvragen.

Als u bijvoorbeeld een sleutel probeert op te halen die niet bestaat in uw Azure Key Vault, wordt er een 404 fout geretourneerd met de melding 'Niet gevonden'.

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

U ziet dat aanvullende informatie wordt geregistreerd, zoals de clientaanvraag-id van de bewerking.

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

Volgende stappen

In deze GitHub-opslagplaats zijn verschillende voorbeelden van clientbibliotheek met Azure Key Vault-sleutels voor u beschikbaar. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met Azure Key Vault:

• Sample1_HelloWorld.md: voor het werken met Azure Key Vault, waaronder:

  • Een sleutel maken
  • Een bestaande sleutel ophalen
  • Een bestaande sleutel bijwerken
  • Een sleutel verwijderen

• Sample2_BackupAndRestore.md - Bevat de codefragmenten die werken met Azure Key Vault-sleutels, waaronder:

  • Een back-up maken van een sleutel en deze herstellen

• Sample3_GetKeys.md - Voorbeeldcode voor het werken met Azure Key Vault-sleutels, waaronder:

  • Sleutels maken
  • Alle sleutels in de Key Vault weergeven
  • Sleutels bijwerken in de Key Vault
  • Versies van een opgegeven sleutel weergeven
  • Sleutels verwijderen uit de Key Vault
  • Verwijderde sleutels in de Key Vault weergeven

• Sample4_EncryptDecrypt.md - Voorbeeldcode voor het uitvoeren van cryptografische bewerkingen met Azure Key Vault-sleutels, waaronder:

  • Gegevens versleutelen en ontsleutelen met de CryptographyClient

• Sample5_SignVerify.md - Voorbeeldcode voor het werken met Azure Key Vault-sleutels, waaronder:

  • Een vooraf berekende samenvatting ondertekenen en de handtekening verifiëren met Ondertekenen en verifiëren
  • Onbewerkte gegevens ondertekenen en de handtekening verifiëren met SignData en VerifyData

• Sample6_WrapUnwrap.md - Voorbeeldcode voor het werken met Azure Key Vault-sleutels, waaronder:

  • Een symmetrische sleutel verpakken en uitpakken

Aanvullende documentatie

• Zie de API-referentiedocumentatie voor uitgebreidere documentatie over Azure Key Vault.
• Zie Geheimen-clientbibliotheek voor geheimen voor clientbibliotheek van Geheimen.
• Zie Clientbibliotheek certificaten voor clientbibliotheek voor certificaten.

Bijdragen

Zie de CONTRIBUTING.md voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheken.

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.