Azure KeyVault-administrationsklientbibliotek för .NET – version 4.3.0

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.

Azure Key Vault administrationsbiblioteksklienter stöder administrativa uppgifter, till exempel fullständig säkerhetskopiering/återställning och rollbaserad åtkomstkontroll på nyckelnivå (RBAC).

| Källkod Paket (NuGet) | Produktdokumentation | Prover

Komma igång

Installera paketet

Installera Azure Key Vault administrationsklientbiblioteket för .NET med NuGet:

dotnet add package Azure.Security.KeyVault.Administration

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 CLI.
• Auktorisering till en befintlig Azure-Key Vault med antingen RBAC (rekommenderas) eller åtkomstkontroll.

Kör följande CLI-kommando för att skapa en Hanterad HSM-resurs:

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 Tjänsten Azure Key Vault måste du skapa en instans av klientklasserna nedan. 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. 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

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

Kontrollera åtkomsten till din hanterade HSM

De utsedda administratörer som tilldelas när de skapas läggs automatiskt till i den inbyggda rollen "Managed HSM-administratörer", som kan ladda ned en säkerhetsdomän och hantera roller för åtkomst till dataplanet, bland andra begränsade behörigheter.

Om du vill utföra andra åtgärder på nycklar måste du tilldela huvudkonton till andra roller, till exempel "Managed HSM Crypto User", som kan utföra icke-destruktiva nyckelåtgärder:

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>

Läs metodtipsen för korrekt skydd av din hanterade HSM.

Skapa KeyVaultAccessControlClient

Instansiera en DefaultAzureCredential för att skicka till KeyVaultAccessControlClient. Samma instans av en tokenautentiseringsuppgift kan användas med flera klienter om de ska autentiseras med samma identitet.

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

Skapa KeyVaultBackupClient

Instansiera en DefaultAzureCredential för att skicka till KeyVaultBackupClient. Samma instans av en tokenautentiseringsuppgift kan användas med flera klienter om de ska autentiseras med samma identitet.

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

Skapa KeyVaultSettingClient

Instansiera en DefaultAzureCredential för att skicka till KeyVaultSettingsClient. Samma instans av en tokenautentiseringsuppgift kan användas med flera klienter om de ska autentiseras med samma identitet.

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

Viktiga begrepp

KeyVaultRoleDefinition

A KeyVaultRoleDefinition är en samling behörigheter. En rolldefinition definierar de åtgärder som kan utföras, till exempel läsa, skriva och ta bort. Den kan också definiera de åtgärder som undantas från tillåtna åtgärder.

KeyVaultRoleDefinitions kan visas och anges som en del av en KeyVaultRoleAssignment.

KeyVaultRoleAssignment

A KeyVaultRoleAssignment är associationen mellan en KeyVaultRoleDefinition och ett huvudnamn för tjänsten. De kan skapas, visas, hämtas individuellt och tas bort.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient tillhandahåller både synkrona och asynkrona åtgärder som möjliggör hantering av KeyVaultRoleDefinition - och KeyVaultRoleAssignment -objekt.

KeyVaultBackupClient

A KeyVaultBackupClient innehåller både synkrona och asynkrona åtgärder för att utföra fullständiga nyckelsäkerhetskopior, fullständiga nyckelåterställningar och selektiva nyckelåterställningar.

BackupOperation

En BackupOperation representerar en tidskrävande åtgärd för en fullständig nyckelsäkerhetskopiering.

RestoreOperation

En RestoreOperation representerar en tidskrävande åtgärd för både en fullständig nyckel och selektiv nyckelåterställning.

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.Administration stöder synkrona och asynkrona API:er.

Följande avsnitt innehåller flera kodfragment som använder ovanstående client kodfragment för antingen åtkomstkontroll- eller säkerhetskopieringsklienter, som omfattar några av de vanligaste uppgifterna för Åtkomstkontroll i Azure Key Vault:

Synkroniseringsexempel

• Åtkomstkontroll
  • Lista alla rolldefinitioner
  • Visa en lista över alla rolltilldelningar
  • Skapa en rolltilldelning
  • Hämta en rolltilldelning
  • Ta bort en rolltilldelning
• Säkerhetskopiering och återställning
  • Utföra en fullständig nyckelsäkerhetskopiering
  • Utföra en fullständig nyckelåterställning

Asynkrona exempel

• Åtkomstkontroll
  • Lista alla rolldefinitioner
  • Visa en lista över alla rolltilldelningar
  • Skapa en rolltilldelning
  • Hämta en rolltilldelning
  • Ta bort en rolltilldelning
• Säkerhetskopiering och återställning
  • Utföra en fullständig nyckelsäkerhetskopiering
  • Utföra en fullständig nyckelåterställning

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 Administration-biblioteket 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 rolltilldelning som inte finns i azure-Key Vault returneras ett 404 fel som anger "Hittades inte".

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

Konfigurera konsolloggning

Det enklaste sättet att se loggarna är att aktivera konsolloggning. Om du vill skapa en Azure SDK-logglyssnare som matar ut meddelanden till konsolen använder du AzureEventSourceListener.CreateConsoleLogger metoden .

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

Mer information om andra loggningsmekanismer finns här.

Nästa steg

Kom igång med våra exempel.

Bidra

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.

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örandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.