Az Azure Key Vault kulcs ügyfélkódtára a .NET-hez – 4.5.0-s verzió
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
- Egy Azure-előfizetés.
- Egy meglévő Azure-Key Vault. Ha létre kell hoznia egy Azure-Key Vault, használhatja az Azure Portalt vagy az Azure CLI-t.
- Engedélyezés meglévő Azure-Key Vault RBAC használatával (ajánlott) vagy hozzáférés-vezérléssel.
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 KeyClient
kö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 CryptographyClient
kö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
- Kulcs létrehozása
- Kulcs lekérése
- Meglévő kulcs frissítése
- Kulcs törlése
- Kulcs törlése és törlése
- Listakulcsok
- Titkosítás és visszafejtés
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
GetKey
leké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
UpdateKeyProperties
frissí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
StartDeleteKey
elindí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 CancellationToken
megszakí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ó
- Az Azure Key Vault részletesebb dokumentációját az API referenciadokumentációjában találja.
- A Titkos ügyfélkódtárakért lásd: Titkos ügyfélkódtár.
- A Tanúsítványok ügyfélkódtárért lásd: Tanúsítványok ügyfélkódtár.
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.
Azure SDK for .NET