Klientská knihovna pro správu Azure KeyVault pro .NET – verze 4.3.0

  • Článek

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.

Klienti knihovny pro správu Azure Key Vault podporují úlohy správy, jako je úplné zálohování a obnovení a řízení přístupu na základě role (RBAC) na úrovni klíče.

Zdrojový kód | Balíček (NuGet) | Dokumentace k | produktu Vzorky

Začínáme

Instalace balíčku

Nainstalujte klientskou knihovnu pro správu Azure Key Vault pro .NET pomocí NuGetu:

dotnet add package Azure.Security.KeyVault.Administration

Požadavky

Pokud chcete vytvořit 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 níže uvedených tříd klientů. 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, který je vhodný pro většinu scénářů, včetně místního vývojového a produkčního prostředí. 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

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í (kvora).

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-managed-hsm-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

Řízení přístupu ke spravovanému HSM

Určení správci přiřazení při vytváření se automaticky přidají do předdefinované role Správci spravovaného HSM, kteří můžou kromě jiných omezených oprávnění stáhnout doménu zabezpečení a spravovat role pro přístup k rovině dat.

Pokud chcete s klíči provádět další akce, musíte objekty zabezpečení přiřadit jiným rolím, jako je například "Spravovaný kryptografický uživatel HSM", které můžou provádět nedestruktivní operace s klíči:

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

Přečtěte si osvědčené postupy pro správné zabezpečení spravovaného HSM.

Vytvoření KeyVaultAccessControlClient

Vytvoření instance pro DefaultAzureCredential předání do objektu KeyVaultAccessControlClient. Stejnou instanci přihlašovacích údajů tokenu je možné použít s více klienty, pokud budou ověřovat pomocí stejné identity.

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Vytvoření KeyVaultBackupClient

Vytvoření instance pro DefaultAzureCredential předání do objektu KeyVaultBackupClient. Stejnou instanci přihlašovacích údajů tokenu je možné použít s více klienty, pokud budou ověřovat pomocí stejné identity.

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Vytvoření KeyVaultSettingClient

Vytvoření instance pro DefaultAzureCredential předání do objektu KeyVaultSettingsClient. Stejnou instanci přihlašovacích údajů tokenu je možné použít s více klienty, pokud budou ověřovat pomocí stejné identity.

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Klíčové koncepty

Definice role služby KeyVault

A KeyVaultRoleDefinition je kolekce oprávnění. Definice role definuje operace, které je možné provádět, jako je čtení, zápis a odstranění. Může také definovat operace, které jsou vyloučené z povolených operací.

Definice KeyVaultRoleDefinitions je možné vypsat a zadat jako součást KeyVaultRoleAssignment.

KeyVaultRoleAssignment

A KeyVaultRoleAssignment je přidružení definice KeyVaultRoleDefinition k instančnímu objektu. Můžete je vytvářet, vypisovat, načítat jednotlivě a odstraňovat.

KeyVaultAccessControlClient

Poskytuje KeyVaultAccessControlClient synchronní i asynchronní operace, které umožňují správu KeyVaultRoleDefinition objektů a KeyVaultRoleAssignment .

KeyVaultBackupClient

Poskytuje KeyVaultBackupClient synchronní i asynchronní operace pro provádění úplného zálohování klíčů, obnovení úplného klíče a selektivního obnovení klíčů.

BackupOperation

Představuje BackupOperation dlouhotrvající operaci pro úplné zálohování klíče.

RestoreOperation

A RestoreOperation představuje dlouhotrvající operaci pro obnovení úplného i selektivního klíče.

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.Administration podporuje synchronní a asynchronní rozhraní API.

Následující část obsahuje několik fragmentů kódu, které používají client výše vytvořený kód pro klienty řízení přístupu nebo pro zálohovací klienty, a pokrývá některé z nejběžnějších úloh souvisejících s řízením přístupu Azure Key Vault:

Příklady synchronizace

Příklady asynchronních funkcí

Ř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 knihovnou azure Key Vault Administration 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 přiřazení role, které v Azure Key Vault neexistuje, vrátí se chyba s oznámením 404 Nenalezena.

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

Nastavení protokolování konzoly

Nejjednodušší způsob, jak zobrazit protokoly, je povolit protokolování konzoly. K vytvoření naslouchacího procesu protokolů sady Azure SDK, který vypíše zprávy do konzoly, použijte metodu AzureEventSourceListener.CreateConsoleLogger .

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Další informace o dalších mechanismech protokolování najdete tady.

Další kroky

Začněte s našimi ukázkami.

Přispívání

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

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