Az Azure Key Vault kulcs ügyfélkódtára a .NET-hez – 4.5.0-s verzió

  • Cikk

Az Azure Key Vault egy felhőalapú szolgáltatás, amely biztonságos kulcstárolást biztosít az adatok titkosításához. Az Azure Key Vault több kulcs és ugyanazon kulcs több verziója is megtartható. Az Azure Key Vault titkosítási kulcsai JSON-webkulcs-objektumokként (JWK) jelennek meg.

Az Azure Key Vault managed HSM egy teljes körűen felügyelt, magas rendelkezésre állású, egybérlős, szabványoknak megfelelő felhőszolgáltatás, amely lehetővé teszi a titkosítási kulcsok védelmét a felhőalkalmazások számára a FIPS 140-2 3. szintű ellenőrzött HSM-ekkel.

Az Azure Key Vault kulcstár-ügyfél támogatja az RSA-kulcsokat és az EC-kulcsokat, amelyek mindegyike támogatja a hardveres biztonsági modulokat (HSM). Műveleteket kínál a kulcsok és azok verzióinak létrehozásához, lekéréséhez, frissítéséhez, törléséhez, törléséhez, törléséhez, biztonsági mentéséhez, visszaállításához és listázásához.

Forráskód | Csomag (NuGet) | API-referenciadokumentáció | Termékdokumentáció | Minták | Migrálási útmutató

Első lépések

A csomag telepítése

Telepítse az Azure Key Vault keys ügyfélkódtárat a .NET-hez a NuGet használatával:

dotnet add package Azure.Security.KeyVault.Keys

Előfeltételek

Ha szabványos Key Vault erőforrást hoz létre, futtassa a következő parancssori felületi parancsot a saját egyedi nevére cserélve <your-resource-group-name><your-key-vault-name>:

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

Felügyelt HSM-erőforrás létrehozásakor futtassa a következő CLI-parancsot:

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

A lekéréshez <your-user-object-id> futtassa a következő parancssori felületi parancsot:

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

Az ügyfél hitelesítése

Az Azure Key Vault szolgáltatás használatához létre kell hoznia a KeyClient osztály egy példányát. Szüksége van egy tároló URL-címére, amelyet "DNS-név" néven láthat a portálon, valamint hitelesítő adatokra egy ügyfélobjektum példányosításához.

Az alábbi példákban egy DefaultAzureCredential, amely a legtöbb forgatókönyvhez megfelelő, beleértve a helyi fejlesztési és éles környezeteket is, amelyek felügyelt identitás-hitelesítést használnak. Emellett azt is javasoljuk, hogy felügyelt identitást használjon a hitelesítéshez éles környezetben. A hitelesítés különböző módjairól és a hozzájuk tartozó hitelesítő adatok típusairól az Azure Identity dokumentációjában talál további információt.

Az alább látható szolgáltató vagy az DefaultAzureCredential Azure SDK-hoz biztosított egyéb hitelesítőadat-szolgáltatók használatához először telepítenie kell az Azure.Identity csomagot:

dotnet add package Azure.Identity

A felügyelt HSM aktiválása

Ez a szakasz csak felügyelt HSM létrehozásakor érvényes. A HSM aktiválásáig minden adatsík-parancs le van tiltva. Nem fog tudni kulcsokat létrehozni vagy szerepköröket hozzárendelni. Csak a létrehozási parancs során hozzárendelt kijelölt rendszergazdák aktiválhatják a HSM-et. A HSM aktiválásához le kell töltenie a biztonsági tartományt.

A HSM aktiválásához a következőkre van szüksége:

  • Minimum 3 RSA kulcspár (maximum 10)
  • Adja meg a biztonsági tartomány (kvórum) visszafejtéséhez szükséges kulcsok minimális számát

A HSM aktiválásához legalább 3 (legfeljebb 10) RSA nyilvános kulcsot kell küldenie a HSM-nek. A HSM ezekkel a kulcsokkal titkosítja a biztonsági tartományt, és visszaküldi. A biztonsági tartomány sikeres letöltése után a HSM készen áll a használatra. Meg kell adnia a kvórumot is, amely a biztonsági tartomány visszafejtéséhez szükséges titkos kulcsok minimális száma.

Az alábbi példa bemutatja, hogyan hozhat létre 3 önaláírt tanúsítványt az openssl használatával.

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 A paranccsal töltse le a biztonsági tartományt, és aktiválja a felügyelt HSM-et. Az alábbi példa 3 RSA-kulcspárt használ (ehhez a parancshoz csak nyilvános kulcsokra van szükség), és a kvórum értékét 2-re állítja.

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 létrehozása

Példányosítsa az a-t DefaultAzureCredential az ügyfélnek való továbbításhoz. A jogkivonat hitelesítő adatainak ugyanazon példánya több ügyféllel is használható, ha ugyanazzal az identitással hitelesíti őket.

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

Kriptográfia létrehozásaÜgyfél

Miután létrehozott egy azure-Key VaultKeyVaultKey, létrehozhatja a CryptographyClientet is:

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

Fő fogalmak

KeyVaultKey

Az Azure Key Vault több kulcstípust és algoritmust támogat, és lehetővé teszi a hardveres biztonsági modulok (HSM) használatát a nagy értékű kulcsokhoz.

KeyClient

A KeyClient szinkron és aszinkron műveleteket biztosító szolgáltatás az SDK-ban létezik, amely lehetővé teszi egy ügyfél kiválasztását az alkalmazás használati esete alapján. A inicializálást KeyClientkövetően az Azure Key Vault elsődleges erőforrástípusaival is kommunikálhat.

KriptográfiaClient

A CryptographyClient szinkron és aszinkron műveleteket biztosító szolgáltatás az SDK-ban létezik, amely lehetővé teszi egy ügyfél kiválasztását az alkalmazás használati esete alapján. A inicializálást CryptographyClientkövetően a használatával titkosítási műveleteket hajthat végre az Azure Key Vault tárolt kulcsokkal.

Menetbiztonság

Garantáljuk, hogy minden ügyfélpéldány-metódus szálbiztos és független egymástól (iránymutatás). Ez biztosítja, hogy az ügyfélpéldányok újrafelhasználására vonatkozó javaslat mindig biztonságos legyen, még a szálak között is.

További fogalmak

Ügyfélbeállítások | A válasz | elérése Hosszú ideig futó műveletek | Hibák | kezelése Diagnosztika | Gúnyos | Ügyfélélettartam

Példák

Az Azure.Security.KeyVault.Keys csomag támogatja a szinkron és aszinkron API-kat.

A következő szakasz a fent létrehozott kódrészleteket tartalmazzaclient, amelyek a leggyakoribb Azure Key Vault szolgáltatással kapcsolatos feladatokat ismertetik:

Példák szinkronizálása

Példák aszinkronizálásra

Kulcs létrehozása

Hozzon létre egy kulcsot, amely az Azure Key Vault tárolandó. Ha már létezik ugyanazzal a névvel rendelkező kulcs, akkor létrejön a kulcs új verziója.

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

Kulcs lekérése

GetKeylekéri a korábban az Azure Key Vault tárolt kulcsot.

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

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

Meglévő kulcs frissítése

UpdateKeyPropertiesfrissíti a korábban az Azure Key Vault tárolt kulcsot.

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

Kulcs törlése

StartDeleteKeyelindít egy hosszú ideig futó műveletet az Azure Key Vault korábban tárolt kulcs törléséhez. A kulcsot azonnal lekérheti anélkül, hogy megvárja a művelet befejezését. Ha a helyreállítható törlés nincs engedélyezve az Azure Key Vault esetében, ez a művelet véglegesen törli a kulcsot.

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

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

Kulcs törlése és törlése

A kulcs végleges törlése vagy helyreállítása előtt meg kell várnia, amíg a hosszú ideig futó művelet befejeződik.

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

Listakulcsok

Ez a példa a megadott Azure Key Vault összes kulcsát felsorolja.

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

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

Titkosítás és visszafejtés

Ez a példa létrehoz egy CryptographyClient értéket, és a használatával titkosítja és visszafejti egy kulccsal az 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);

Kulcs létrehozása aszinkron módon

Az aszinkron API-k megegyeznek a szinkron megfelelőikkel, de az aszinkron metódusok tipikus "Async" utótagjával térnek vissza, és feladatokat adnak vissza.

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

Listakulcsok aszinkron módon

A listakulcsok nem a metódusra GetPropertiesOfKeysAsync várnak, hanem az utasítással await foreach használható értéket AsyncPageable<KeyProperties> ad vissza:

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

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

Kulcs aszinkron törlése

Ha egy kulcsot aszinkron módon töröl, mielőtt véglegesítené, megvárhatja a metódust a WaitForCompletionAsync műveletben. Alapértelmezés szerint ez a hurok határozatlan ideig működik, de egy parancs átadásával CancellationTokenmegszakíthatja azt.

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

Hibaelhárítás

A különböző hibaforgatókönyvek diagnosztizálásával kapcsolatos részletekért tekintse meg a hibaelhárítási útmutatónkat .

Általános kérdések

Amikor az Azure Key Vault kulcs ügyfélkódtárával a .NET SDK-t használja, a szolgáltatás által visszaadott hibák megegyeznek a REST API-kérésekhez visszaadott HTTP-állapotkódokkal.

Ha például olyan kulcsot próbál lekérni, amely nem létezik az Azure-Key Vault, a rendszer hibát 404 ad vissza, amely "Nem található".

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

Megfigyelheti, hogy a rendszer további adatokat naplóz, például a művelet ügyfélkérési azonosítóját.

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

Következő lépések

Ebben a GitHub-adattárban számos Azure Key Vault kulcs ügyfélkódtár-minta érhető el. Ezek a minták az Azure-Key Vault használata során gyakran előforduló további forgatókönyvekhez nyújtanak példakódot:

  • Sample1_HelloWorld.md – az Azure Key Vault használata, beleértve a következőket:

    • Kulcs létrehozása
    • Meglévő kulcs lekérése
    • Meglévő kulcs frissítése
    • Kulcs törlése

  • Sample2_BackupAndRestore.md – Az Azure Key Vault-kulcsokkal működő kódrészleteket tartalmazza, beleértve a következőket:

    • Kulcs biztonsági mentése és helyreállítása

  • Sample3_GetKeys.md – Példakód az Azure Key Vault-kulcsok használatára, beleértve a következőket:

    • Kulcsok létrehozása
    • A Key Vault összes kulcsának listázása
    • Kulcsok frissítése a Key Vault
    • Adott kulcs verzióinak listázása
    • Kulcsok törlése a Key Vault
    • Törölt kulcsok listázása a Key Vault

  • Sample4_EncryptDecrypt.md – Példakód az Azure Key Vault kulcsokkal végzett titkosítási műveletek végrehajtásához, beleértve a következőket:

    • Adatok titkosítása és visszafejtése a CryptographyClient használatával

  • Sample5_SignVerify.md – Példakód az Azure Key Vault-kulcsok használatára, beleértve a következőket:

    • Előre kiszámított kivonat aláírása és az aláírás ellenőrzése a Sign and Verify (Aláírás és ellenőrzés) használatával
    • Nyers adatok aláírása és az aláírás ellenőrzése a SignData és a VerifyData használatával

  • Sample6_WrapUnwrap.md – Példakód az Azure Key Vault-kulcsok használatára, beleértve a következőket:

    • Szimmetrikus kulcs körbefuttatása és kicsomagolása

További dokumentáció

Közreműködés

A kódtárak létrehozásával, tesztelésével és közreműködésével kapcsolatos részletekért tekintse meg a CONTRIBUTING.md.

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.

Megjelenések