Klientská knihovna klíčů Azure Key Vault pro .NET – verze 4.5.0

  • Článek

Azure Key Vault je cloudová služba, která poskytuje zabezpečené úložiště klíčů pro šifrování dat. V Azure Key Vault je možné uchovávat více klíčů a více verzí stejného klíče. Kryptografické klíče v Azure Key Vault jsou reprezentované jako objekty JSON Web Key (JWK).

Azure Key Vault Managed HSM je plně spravovaná, vysoce dostupná cloudová služba s jedním tenantem kompatibilní se standardy, která umožňuje chránit kryptografické klíče pro cloudové aplikace pomocí modulů HSM ověřených standardem FIPS 140-2 Level 3.

Klient knihovny klíčů Azure Key Vault podporuje klíče RSA a klíče EC (Elliptic Curve) s odpovídající podporou v modulech hardwarového zabezpečení (HSM). Nabízí operace pro vytvoření, načtení, aktualizaci, odstranění, vymazání, zálohování, obnovení a výpis klíčů a jejich verzí.

Zdrojový kód | Balíček (NuGet) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky | Průvodce migrací

Začínáme

Instalace balíčku

Nainstalujte klientskou knihovnu klíčů Azure Key Vault pro .NET pomocí NuGetu:

dotnet add package Azure.Security.KeyVault.Keys

Požadavky

Pokud vytváříte standardní Key Vault prostředek, spusťte následující příkaz rozhraní příkazového řádku a nahraďte <your-resource-group-name><your-key-vault-name> a vlastními jedinečnými názvy:

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

Pokud vytváříte prostředek spravovaného HSM, spusťte následující příkaz rozhraní příkazového řádku:

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

Pokud to chcete získat <your-user-object-id> , můžete spustit následující příkaz rozhraní příkazového řádku:

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

Ověření klienta

Pokud chcete pracovat se službou Azure Key Vault, budete muset vytvořit instanci třídy KeyClient. Potřebujete adresu URL trezoru, která se na portálu může zobrazit jako Název DNS, a přihlašovací údaje k vytvoření instance objektu klienta.

V níže uvedených příkladech se používá DefaultAzureCredential, což je vhodné pro většinu scénářů, včetně místních vývojových a produkčních prostředí využívajících ověřování spravované identity. Kromě toho doporučujeme pro ověřování v produkčních prostředích používat spravovanou identitu. Další informace o různých způsobech ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci ke službě Azure Identity .

Pokud chcete použít DefaultAzureCredential níže uvedeného zprostředkovatele nebo jiné zprostředkovatele přihlašovacích údajů poskytované se sadou Azure SDK, musíte nejprve nainstalovat balíček Azure.Identity:

dotnet add package Azure.Identity

Aktivace spravovaného HSM

Tato část platí jenom v případě, že vytváříte spravovaný HSM. Všechny příkazy roviny dat jsou zakázané, dokud se modul hardwarového zabezpečení neaktivuje. Nebudete moct vytvářet klíče ani přiřazovat role. Modul hardwarového zabezpečení můžou aktivovat jenom určení správci, kteří byli přiřazeni během příkazu create. Pokud chcete modul hardwarového zabezpečení aktivovat, musíte stáhnout doménu zabezpečení.

K aktivaci HSM potřebujete:

  • Minimálně 3 páry klíčů RSA (maximálně 10)
  • Zadejte minimální počet klíčů potřebných k dešifrování domény zabezpečení (kvorum).

Pokud chcete hsm aktivovat, odešlete mu alespoň 3 (maximálně 10) veřejných klíčů RSA. Modul hardwarového zabezpečení pomocí těchto klíčů zašifruje doménu zabezpečení a odešle ji zpět. Po úspěšném stažení této domény zabezpečení je váš HSM připravený k použití. Musíte také zadat kvorum, což je minimální počet privátních klíčů potřebných k dešifrování domény zabezpečení.

Následující příklad ukazuje, jak pomocí openssl vygenerovat 3 certifikáty podepsané svým držitelem.

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

Pomocí příkazu az keyvault security-domain download stáhněte doménu zabezpečení a aktivujte spravovaný HSM. Následující příklad používá 3 páry klíčů RSA (pro tento příkaz jsou potřeba pouze veřejné klíče) a nastaví kvorum na 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

Vytvoření KeyClient

Vytvořte instanci , která DefaultAzureCredential se má předat klientovi. Stejnou instanci přihlašovacích údajů tokenu je možné použít s více klienty, pokud budou ověřovat pomocí stejné identity.

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

Vytvořit kryptografický klient

Po vytvoření objektu KeyVaultKey v Azure Key Vault můžete také vytvořit kryptografický klient:

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

Klíčové koncepty

Klíč trezoru klíčů

Azure Key Vault podporuje několik typů klíčů a algoritmů a umožňuje používat moduly hardwarového zabezpečení (HSM) pro klíče s vysokou hodnotou.

KeyClient

Sada KeyClient SDK poskytuje synchronní i asynchronní operace, které umožňují výběr klienta na základě případu použití aplikace. Jakmile inicializujete KeyClient, můžete pracovat s primárními typy prostředků v Azure Key Vault.

Kryptografický klient

Sada CryptographyClient SDK poskytuje synchronní i asynchronní operace, které umožňují výběr klienta na základě případu použití aplikace. Jakmile inicializujete CryptographyClient, můžete ho použít k provádění kryptografických operací s klíči uloženými v Azure Key Vault.

Bezpečnost vlákna

Zaručujeme, že všechny metody instance klienta jsou bezpečné pro přístup z více vláken a nezávislé na sobě (pokyny). Tím se zajistí, že doporučení opakovaně používat instance klienta je vždy bezpečné, a to i napříč vlákny.

Další koncepty

Možnosti | klienta Přístup k odpovědi | Dlouhotrvající operace | Zpracování selhání | Diagnostika | Zesměšňovat | Životnost klienta

Příklady

Balíček Azure.Security.KeyVault.Keys podporuje synchronní a asynchronní rozhraní API.

Následující část obsahuje několik fragmentů kódu pomocí clientvýše vytvořeného kódu, které pokrývají některé z nejběžnějších úloh souvisejících se službou Azure Key Vault klíč:

Příklady synchronizace

Příklady asynchronních funkcí

Vytvoření klíče

Vytvořte klíč, který se uloží do Key Vault Azure. Pokud už klíč se stejným názvem existuje, vytvoří se nová verze klíče.

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

Načtení klíče

GetKeynačte klíč dříve uložený v Azure Key Vault.

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

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

Aktualizace existujícího klíče

UpdateKeyPropertiesaktualizuje klíč dříve uložený v 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);

Odstranění klíče

StartDeleteKeyspustí dlouhotrvající operaci, která odstraní klíč dříve uložený v Azure Key Vault. Klíč můžete načíst okamžitě, aniž byste museli čekat na dokončení operace. Pokud pro azure Key Vault není povolené obnovitelné odstranění, tato operace trvale odstraní klíč.

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

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

Odstranění a vymazání klíče

Než se pokusíte klíč vyprázdnit nebo obnovit, budete muset počkat na dokončení dlouhotrvající operace.

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

Výpis klíčů

Tento příklad vypíše všechny klíče v zadaném Key Vault Azure.

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

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

Šifrování a dešifrování

Tento příklad vytvoří CryptographyClient objekt a použije ho k šifrování a dešifrování pomocí klíče v 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);

Asynchronní vytvoření klíče

Asynchronní rozhraní API jsou shodná s jejich synchronními protějšky, ale vrací se s typickou příponou "Async" pro asynchronní metody a vrací úlohu.

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

Asynchronní výpis klíčů

Výpis klíčů nespoléhá na čekání na metodu GetPropertiesOfKeysAsync , ale vrátí hodnotu AsyncPageable<KeyProperties> , kterou můžete použít s příkazem await foreach :

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

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

Asynchronní odstranění klíče

Při asynchronním odstraňování klíče před vyprázdněním můžete počkat na metodu WaitForCompletionAsync operace. Ve výchozím nastavení se tato smyčka trvale smyče, ale můžete ji zrušit předáním CancellationTokenpříkazu .

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

Řešení potíží

Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v našem průvodci odstraňováním potíží.

Obecné

Při interakci s klientskou knihovnou klíčů Azure Key Vault pomocí sady .NET SDK odpovídají chyby vrácené službou stejným stavovým kódům HTTP vráceným pro požadavky rozhraní REST API.

Pokud se například pokusíte načíst klíč, který v Azure Key Vault neexistuje, vrátí se chyba s oznámením 404 Nenalezena.

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

Všimněte si, že se protokolují další informace, například ID požadavku klienta operace.

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

Další kroky

V tomto úložišti GitHub máte k dispozici několik ukázek klientské knihovny klíčů Azure Key Vault klíčů. Tyto ukázky poskytují příklad kódu pro další scénáře, se kterými se při práci s Azure Key Vault běžně setkáváme:

  • Sample1_HelloWorld.md – pro práci s Azure Key Vault, včetně:

    • Vytvoření klíče
    • Získání existujícího klíče
    • Aktualizace existujícího klíče
    • Odstranění klíče

  • Sample2_BackupAndRestore.md – obsahuje fragmenty kódu, které pracují s klíči Azure Key Vault, včetně následujících:

    • Zálohování a obnovení klíče

  • Sample3_GetKeys.md – příklad kódu pro práci s klíči Azure Key Vault, včetně následujících:

    • Vytvoření klíčů
    • Výpis všech klíčů v Key Vault
    • Aktualizace klíčů v Key Vault
    • Výpis verzí zadaného klíče
    • Odstranění klíčů z Key Vault
    • Výpis odstraněných klíčů v Key Vault

  • Sample4_EncryptDecrypt.md – příklad kódu pro provádění kryptografických operací s využitím klíčů Azure Key Vault, včetně následujících:

    • Šifrování a dešifrování dat pomocí CryptographyClient

  • Sample5_SignVerify.md – příklad kódu pro práci s klíči Azure Key Vault, včetně následujících:

    • Podepsání předem vypočteného přehledu a ověření podpisu pomocí funkce Sign and Verify
    • Podepsání nezpracovaných dat a ověření podpisu pomocí SignData a VerifyData

  • Sample6_WrapUnwrap.md – příklad kódu pro práci s klíči Azure Key Vault, včetně následujících:

    • Zabalení a rozbalení symetrického klíče

Další dokumentace

Přispívání

Podrobnosti o sestavování, testování a přispívání do těchto knihoven najdete v CONTRIBUTING.md .

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Imprese