Azure Key Vault nyckelklientbibliotek för .NET – version 4.5.0

Azure Key Vault är en molntjänst som tillhandahåller säker lagring av nycklar för kryptering av dina data. Flera nycklar och flera versioner av samma nyckel kan lagras i Azure-Key Vault. Kryptografiska nycklar i Azure Key Vault representeras som JWK-objekt (JSON Web Key).

Azure Key Vault Managed HSM är en fullständigt hanterad, högtillgänglig molntjänst som är kompatibel med en enda klientorganisation och som gör att du kan skydda kryptografiska nycklar för dina molnprogram med FIPS 140-2 Level 3-verifierade HSM:er.

Biblioteksklienten för Azure Key Vault-nycklar stöder RSA-nycklar och EC-nycklar (Elliptic Curve), var och en med motsvarande stöd i maskinvarusäkerhetsmoduler (HSM). Den erbjuder åtgärder för att skapa, hämta, uppdatera, ta bort, rensa, säkerhetskopiera, återställa och lista nycklarna och dess versioner.

| Källkod Paket (NuGet) | API-referensdokumentation | Produktdokumentation | Prover | Migreringsguide

Komma igång

Installera paketet

Installera klientbiblioteket för Azure Key Vault-nycklar för .NET med NuGet:

dotnet add package Azure.Security.KeyVault.Keys

Förutsättningar

• En Azure-prenumeration.
• En befintlig Azure-Key Vault. Om du behöver skapa en Azure-Key Vault kan du använda Azure-portalen eller Azure CLI.
• Auktorisering till en befintlig Azure-Key Vault med antingen RBAC (rekommenderas) eller åtkomstkontroll.

Om du skapar en standardresurs Key Vault kör du följande CLI-kommando och <your-resource-group-name> ersätter och <your-key-vault-name> med dina egna unika namn:

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

Om du skapar en Hanterad HSM-resurs kör du följande CLI-kommando:

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

Du kan hämta <your-user-object-id> genom att köra följande CLI-kommando:

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

Autentisera klienten

För att kunna interagera med Azure Key Vault-tjänsten måste du skapa en instans av klassen KeyClient. Du behöver en valv-URL som du kan se som "DNS-namn" i portalen och autentiseringsuppgifter för att instansiera ett klientobjekt.

Exemplen som visas nedan använder en DefaultAzureCredential, som är lämplig för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer som använder hanterad identitetsautentisering. Dessutom rekommenderar vi att du använder en hanterad identitet för autentisering i produktionsmiljöer. Du hittar mer information om olika sätt att autentisera och deras motsvarande typer av autentiseringsuppgifter i Azure Identity-dokumentationen .

Om du vill använda providern DefaultAzureCredential som visas nedan, eller andra leverantörer av autentiseringsuppgifter som tillhandahålls med Azure SDK, måste du först installera Azure.Identity-paketet:

dotnet add package Azure.Identity

Aktivera din hanterade HSM

Det här avsnittet gäller endast om du skapar en hanterad HSM. Alla dataplanskommandon inaktiveras tills HSM aktiveras. Du kommer inte att kunna skapa nycklar eller tilldela roller. Endast de utsedda administratörer som tilldelades under kommandot create kan aktivera HSM. Om du vill aktivera HSM måste du ladda ned säkerhetsdomänen.

För att aktivera din HSM behöver du:

• Minst 3 RSA-nyckelpar (högst 10)
• Ange det minsta antal nycklar som krävs för att dekryptera säkerhetsdomänen (kvorum)

För att aktivera HSM skickar du minst 3 (högst 10) offentliga RSA-nycklar till HSM. HSM krypterar säkerhetsdomänen med dessa nycklar och skickar tillbaka den. När den här säkerhetsdomänen har laddats ned är din HSM redo att användas. Du måste också ange kvorum, vilket är det minsta antalet privata nycklar som krävs för att dekryptera säkerhetsdomänen.

Exemplet nedan visar hur du använder openssl för att generera 3 självsignerade certifikat.

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

az keyvault security-domain download Använd kommandot för att ladda ned säkerhetsdomänen och aktivera din hanterade HSM. I exemplet nedan används 3 RSA-nyckelpar (endast offentliga nycklar behövs för det här kommandot) och kvorumet anges till 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

Skapa KeyClient

Instansiera en DefaultAzureCredential som ska skickas till klienten. Samma instans av en tokenautentiseringsuppgift kan användas med flera klienter om de ska autentiseras med samma identitet.

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

Skapa CryptographyClient

När du har skapat en KeyVaultKey i Azure-Key Vault kan du också skapa CryptographyClient:

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

Viktiga begrepp

KeyVaultKey

Azure Key Vault stöder flera nyckeltyper och algoritmer och möjliggör användning av maskinvarusäkerhetsmoduler (HSM) för nycklar med högt värde.

KeyClient

Det KeyClient finns både synkrona och asynkrona åtgärder i SDK:t som gör det möjligt att välja en klient baserat på ett programs användningsfall. När du har initierat en KeyClientkan du interagera med de primära resurstyperna i Azure Key Vault.

CryptographyClient

Det CryptographyClient finns både synkrona och asynkrona åtgärder i SDK:t som gör det möjligt att välja en klient baserat på ett programs användningsfall. När du har initierat en CryptographyClientkan du använda den för att utföra kryptografiska åtgärder med nycklar som lagras i Azure Key Vault.

Trådsäkerhet

Vi garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra (riktlinje). Detta säkerställer att rekommendationen att återanvända klientinstanser alltid är säker, även över trådar.

Ytterligare begrepp

Klientalternativ | Åtkomst till svaret | Tidskrävande åtgärder | Hantera fel | Diagnostik | Gäckande | Klientlivslängd

Exempel

Paketet Azure.Security.KeyVault.Keys stöder synkrona och asynkrona API:er.

Följande avsnitt innehåller flera kodfragment med hjälp av ovanståendeclient, som omfattar några av de vanligaste uppgifterna för Azure Key Vault-nyckeltjänsten:

Synkroniseringsexempel

• Skapa en nyckel
• Hämta en nyckel
• Uppdatera en befintlig nyckel
• Ta bort en nyckel
• Ta bort och rensa en nyckel
• Listnycklar
• Kryptera och dekryptera

Asynkrona exempel

• Skapa en nyckel asynkront
• Visa en lista över nycklar asynkront
• Ta bort en nyckel asynkront

Skapa en nyckel

Skapa en nyckel som ska lagras i Azure Key Vault. Om det redan finns en nyckel med samma namn skapas en ny version av nyckeln.

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

Hämta en nyckel

GetKeyhämtar en nyckel som tidigare lagrats i Azure Key Vault.

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

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

Uppdatera en befintlig nyckel

UpdateKeyPropertiesuppdaterar en nyckel som tidigare lagrats i 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);

Ta bort en nyckel

StartDeleteKeystartar en långvarig åtgärd för att ta bort en nyckel som tidigare lagrats i Azure-Key Vault. Du kan hämta nyckeln direkt utan att vänta på att åtgärden ska slutföras. När mjuk borttagning inte är aktiverat för Azure-Key Vault tar den här åtgärden bort nyckeln permanent.

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

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

Ta bort och rensa en nyckel

Du måste vänta tills den långvariga åtgärden har slutförts innan du försöker rensa eller återställa nyckeln.

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

Listnycklar

I det här exemplet visas alla nycklar i den angivna Azure-Key Vault.

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

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

Kryptera och dekryptera

Det här exemplet skapar en CryptographyClient och använder den för att kryptera och dekryptera med en nyckel i 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);

Skapa en nyckel asynkront

De asynkrona API:erna är identiska med deras synkrona motsvarigheter, men returneras med det typiska "Async"-suffixet för asynkrona metoder och returnerar en aktivitet.

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

Visa en lista över nycklar asynkront

Listning av nycklar förlitar sig inte på att vänta på GetPropertiesOfKeysAsync metoden, men returnerar en AsyncPageable<KeyProperties> som du kan använda med -instruktionen await foreach :

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

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

Ta bort en nyckel asynkront

När du tar bort en nyckel asynkront innan du rensar den kan du vänta WaitForCompletionAsync på metoden för åtgärden. Som standard loopar den här loopen på obestämd tid, men du kan avbryta den genom att skicka en CancellationToken.

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

Felsökning

Se vår felsökningsguide för information om hur du diagnostiserar olika felscenarier.

Allmänt

När du interagerar med Azure Key Vault nyckelklientbiblioteket med hjälp av .NET SDK motsvarar fel som returneras av tjänsten samma HTTP-statuskoder som returneras för REST API-begäranden.

Om du till exempel försöker hämta en nyckel som inte finns i din Azure-Key Vault returneras ett 404 fel som anger "Hittades inte".

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

Du kommer att märka att ytterligare information loggas, till exempel ID för klientbegäran för åtgärden.

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ästa steg

Det finns flera azure Key Vault-nycklar för klientbiblioteksexempel på den här GitHub-lagringsplatsen. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med Azure Key Vault:

• Sample1_HelloWorld.md – för att arbeta med Azure Key Vault, inklusive:

  • Skapa en nyckel
  • Hämta en befintlig nyckel
  • Uppdatera en befintlig nyckel
  • Ta bort en nyckel

• Sample2_BackupAndRestore.md – Innehåller kodfragmenten som fungerar med Azure Key Vault nycklar, inklusive:

  • Säkerhetskopiera och återställa en nyckel

• Sample3_GetKeys.md – Exempelkod för att arbeta med Azure Key Vault-nycklar, inklusive:

  • Skapa nycklar
  • Visa en lista över alla nycklar i Key Vault
  • Uppdatera nycklar i Key Vault
  • Lista versioner av en angiven nyckel
  • Ta bort nycklar från Key Vault
  • Lista borttagna nycklar i Key Vault

• Sample4_EncryptDecrypt.md – Exempelkod för att utföra kryptografiska åtgärder med Azure Key Vault nycklar, inklusive:

  • Kryptera och dekryptera data med CryptographyClient

• Sample5_SignVerify.md – Exempelkod för att arbeta med Azure Key Vault nycklar, inklusive:

  • Signera en förberäknad sammandrag och verifiera signaturen med Signera och verifiera
  • Signera rådata och verifiera signaturen med SignData och VerifyData

• Sample6_WrapUnwrap.md – Exempelkod för att arbeta med Azure Key Vault-nycklar, inklusive:

  • Omsluta och packa upp en symmetrisk nyckel

Ytterligare dokumentation

• Mer omfattande dokumentation om Azure Key Vault finns i API-referensdokumentationen.
• Information om klientbibliotek för hemligheter finns i Klientbibliotek för hemligheter.
• Information om certifikatklientbibliotek finns i Certifikatklientbibliotek.

Bidra

Mer information om hur du skapar, testar och bidrar till dessa bibliotek finns i CONTRIBUTING.md .

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.