Biblioteka klienta klucza usługi Azure Key Vault dla platformy .NET — wersja 4.5.0

Artykuł
04/03/2023

Azure Key Vault to usługa w chmurze, która zapewnia bezpieczny magazyn kluczy do szyfrowania danych. Wiele kluczy i wiele wersji tego samego klucza można przechowywać w usłudze Azure Key Vault. Klucze kryptograficzne w usłudze Azure Key Vault są reprezentowane jako obiekty klucza internetowego JSON (JWK).

Zarządzany moduł HSM platformy Azure Key Vault to w pełni zarządzana, wysoce dostępna, zgodna ze standardami usługa w chmurze, która umożliwia ochronę kluczy kryptograficznych dla aplikacji w chmurze przy użyciu zweryfikowanych modułów HSM fiPS 140-2 poziom 3.

Klient biblioteki kluczy usługi Azure Key Vault obsługuje klucze RSA i klucze krzywej eliptycznej (EC), z których każda obsługuje sprzętowe moduły zabezpieczeń (HSM). Oferuje ona operacje tworzenia, pobierania, aktualizowania, usuwania, przeczyszczania, tworzenia kopii zapasowej, przywracania i wyświetlania listy kluczy i jego wersji.

Wprowadzenie

Instalowanie pakietu

Zainstaluj bibliotekę klienta kluczy usługi Azure Key Vault dla platformy .NET przy użyciu narzędzia NuGet:

dotnet add package Azure.Security.KeyVault.Keys

Wymagania wstępne

Subskrypcja platformy Azure.
Istniejąca usługa Azure Key Vault. Jeśli musisz utworzyć usługę Azure Key Vault, możesz użyć witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.
Autoryzacja do istniejącej usługi Azure Key Vault przy użyciu kontroli dostępu opartej na rolach (zalecanej) lub kontroli dostępu.

Jeśli tworzysz standardowy zasób Key Vault, uruchom następujące polecenie interfejsu wiersza polecenia zastępując <your-resource-group-name> wartości i <your-key-vault-name> własnymi, unikatowymi nazwami:

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

Jeśli tworzysz zasób zarządzanego modułu HSM, uruchom następujące polecenie interfejsu wiersza polecenia:

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

Aby uzyskać dostęp <your-user-object-id> , możesz uruchomić następujące polecenie interfejsu wiersza polecenia:

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

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą Azure Key Vault, należy utworzyć wystąpienie klasy KeyClient. Potrzebny jest adres URL magazynu, który może być widoczny jako "Nazwa DNS" w portalu i poświadczenia do utworzenia wystąpienia obiektu klienta.

W poniższych przykładach użyto DefaultAzureCredentialelementu , który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk programistycznych i produkcyjnych korzystających z uwierzytelniania tożsamości zarządzanej. Ponadto zalecamy używanie tożsamości zarządzanej do uwierzytelniania w środowiskach produkcyjnych. Więcej informacji na temat różnych sposobów uwierzytelniania i odpowiadających im typów poświadczeń można znaleźć w dokumentacji tożsamości platformy Azure .

Aby użyć podanego DefaultAzureCredential poniżej dostawcy lub innych dostawców poświadczeń dostarczanych z zestawem Azure SDK, należy najpierw zainstalować pakiet Azure.Identity:

dotnet add package Azure.Identity

Aktywowanie zarządzanego modułu HSM

Ta sekcja ma zastosowanie tylko w przypadku tworzenia zarządzanego modułu HSM. Wszystkie polecenia płaszczyzny danych są wyłączone do momentu aktywowania modułu HSM. Nie będzie można tworzyć kluczy ani przypisywać ról. Tylko wyznaczeni administratorzy, którzy zostali przypisani podczas tworzenia polecenia, mogą aktywować moduł HSM. Aby aktywować moduł HSM, należy pobrać domenę zabezpieczeń.

Aby aktywować moduł HSM, potrzebne są następujące elementy:

Minimalna 3 pary kluczy RSA (maksymalnie 10)
Określ minimalną liczbę kluczy wymaganych do odszyfrowania domeny zabezpieczeń (kworum)

Aby aktywować moduł HSM, należy wysłać co najmniej 3 (maksymalnie 10) klucze publiczne RSA do modułu HSM. Moduł HSM szyfruje domenę zabezpieczeń przy użyciu tych kluczy i wysyła ją z powrotem. Po pomyślnym pobraniu tej domeny zabezpieczeń moduł HSM jest gotowy do użycia. Należy również określić kworum, czyli minimalną liczbę kluczy prywatnych wymaganych do odszyfrowania domeny zabezpieczeń.

W poniższym przykładzie pokazano, jak używać polecenia openssl do generowania certyfikatu z podpisem własnym 3.

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 Użyj polecenia , aby pobrać domenę zabezpieczeń i aktywować zarządzany moduł HSM. W poniższym przykładzie użyto 3 par kluczy RSA (do tego polecenia są wymagane tylko klucze publiczne) i ustawiono kworum 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

Tworzenie klienta KeyClient

Utwórz wystąpienie elementu DefaultAzureCredential , aby przekazać do klienta. To samo wystąpienie poświadczeń tokenu może być używane z wieloma klientami, jeśli będą uwierzytelniać się przy użyciu tej samej tożsamości.

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

Tworzenie elementu CryptographyClient

Po utworzeniu elementu KeyVaultKey w usłudze Azure Key Vault możesz również utworzyć element CryptographyClient:

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

Kluczowe pojęcia

KeyVaultKey

Usługa Azure Key Vault obsługuje wiele typów kluczy i algorytmów oraz umożliwia korzystanie ze sprzętowych modułów zabezpieczeń (HSM) dla kluczy o wysokiej wartości.

KeyClient

W KeyClient zestawie SDK istnieje zarówno operacje synchroniczne, jak i asynchroniczne, umożliwiające wybór klienta na podstawie przypadku użycia aplikacji. Po zainicjowaniu KeyClientelementu można wchodzić w interakcje z podstawowymi typami zasobów w usłudze Azure Key Vault.

KryptografiaClient

W CryptographyClient zestawie SDK istnieje zarówno operacje synchroniczne, jak i asynchroniczne, umożliwiające wybór klienta na podstawie przypadku użycia aplikacji. Po zainicjowaniu CryptographyClientelementu można go użyć do wykonywania operacji kryptograficznych z kluczami przechowywanymi w usłudze Azure Key Vault.

Bezpieczeństwo wątkowe

Gwarantujemy, że wszystkie metody wystąpienia klienta są bezpieczne wątkowo i niezależne od siebie (wytyczne). Dzięki temu zalecenie ponownego obsługi wystąpień klienta jest zawsze bezpieczne, nawet w wątkach.

Dodatkowe pojęcia

Przykłady

Pakiet Azure.Security.KeyVault.Keys obsługuje interfejsy API synchroniczne i asynchroniczne.

Poniższa sekcja zawiera kilka fragmentów kodu, które zostały clientutworzone powyżej, obejmujące niektóre z najbardziej typowych zadań związanych z usługą Azure Key Vault:

Przykłady asynchroniczne

Asynchronicznie tworzenie klucza
Asynchroniczna lista kluczy
Asynchroniczne usuwanie klucza

Utwórz klucz

Utwórz klucz do przechowywania w usłudze Azure Key Vault. Jeśli klucz o tej samej nazwie już istnieje, zostanie utworzona nowa wersja klucza.

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

Pobieranie klucza

GetKeypobiera klucz wcześniej przechowywany w usłudze Azure Key Vault.

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

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

Aktualizowanie istniejącego klucza

UpdateKeyPropertiesaktualizuje klucz przechowywany wcześniej w usłudze 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);

Usuń klucz

StartDeleteKeyUruchamia długotrwałą operację usuwania klucza wcześniej przechowywanego w usłudze Azure Key Vault. Klucz można pobrać natychmiast bez oczekiwania na ukończenie operacji. Jeśli usuwanie nietrwałe nie jest włączone dla usługi Azure Key Vault, ta operacja trwale usuwa klucz.

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

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

Usuwanie i przeczyszczanie klucza

Przed próbą przeczyszczenia lub odzyskania klucza należy poczekać na ukończenie długotrwałej operacji.

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

Wyświetlanie listy kluczy

W tym przykładzie wymieniono wszystkie klucze w określonej Key Vault platformy Azure.

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

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

Szyfrowanie i odszyfrowywanie

W tym przykładzie tworzony jest obiekt CryptographyClient i używa go do szyfrowania i odszyfrowywania za pomocą klucza w usłudze 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);

Asynchronicznie tworzenie klucza

Asynchroniczne interfejsy API są identyczne z ich synchronicznymi odpowiednikami, ale zwracają z typowym sufiksem "Asynchronicznym" dla metod asynchronicznych i zwracają zadanie.

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

Asynchroniczna lista kluczy

Wyświetlanie kluczy nie polega na oczekiwaniu na metodę GetPropertiesOfKeysAsync , ale zwraca wartość AsyncPageable<KeyProperties> , której można użyć z instrukcją await foreach :

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

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

Asynchroniczne usuwanie klucza

Podczas usuwania klucza asynchronicznie przed przeczyszczeniem można oczekiwać WaitForCompletionAsync na metodę operacji. Domyślnie ta pętla jest w nieskończoność, ale można ją anulować, przekazując CancellationTokenelement .

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

Rozwiązywanie problemów

Zobacz nasz przewodnik rozwiązywania problemów, aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii.

Ogólne

W przypadku interakcji z biblioteką klienta klucza usługi Azure Key Vault przy użyciu zestawu SDK platformy .NET błędy zwrócone przez usługę odpowiadają tym samym kodom stanu HTTP zwróconym dla żądań interfejsu API REST.

Jeśli na przykład spróbujesz pobrać klucz, który nie istnieje w usłudze Azure Key Vault, 404 zostanie zwrócony błąd wskazujący komunikat "Nie znaleziono".

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

Zauważysz, że dodatkowe informacje są rejestrowane, takie jak identyfikator żądania klienta operacji.

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

Następne kroki

Kilka przykładów biblioteki klienta kluczy platformy Azure Key Vault jest dostępnych w tym repozytorium GitHub. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy często napotykanych podczas pracy z usługą Azure Key Vault:

Sample1_HelloWorld.md — do pracy z usługą Azure Key Vault, w tym:
- Utwórz klucz
- Pobieranie istniejącego klucza
- Aktualizowanie istniejącego klucza
- Usuń klucz
Sample2_BackupAndRestore.md — zawiera fragmenty kodu współpracujące z kluczami usługi Azure Key Vault, w tym:
- Tworzenie kopii zapasowej i odzyskiwanie klucza
Sample3_GetKeys.md — przykładowy kod do pracy z kluczami usługi Azure Key Vault, w tym:
- Tworzenie kluczy
- Wyświetlanie listy wszystkich kluczy w Key Vault
- Aktualizowanie kluczy w Key Vault
- Wyświetlanie listy wersji określonego klucza
- Usuwanie kluczy z Key Vault
- Wyświetlanie listy usuniętych kluczy w Key Vault
Sample4_EncryptDecrypt.md — przykładowy kod do wykonywania operacji kryptograficznych przy użyciu kluczy usługi Azure Key Vault, w tym:
- Szyfrowanie i odszyfrowywanie danych za pomocą elementu CryptographyClient
Sample5_SignVerify.md — przykładowy kod do pracy z kluczami usługi Azure Key Vault, w tym:
- Podpisywanie wstępnie obliczonego skrótu i weryfikowanie podpisu przy użyciu znaku i weryfikacji
- Podpisywanie danych pierwotnych i weryfikowanie podpisu przy użyciu funkcji SignData i VerifyData
Sample6_WrapUnwrap.md — przykładowy kod do pracy z kluczami Key Vault platformy Azure, w tym:
- Zawijanie i odpakowywanie klucza symetrycznego

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure Key Vault, zobacz dokumentację referencyjną interfejsu API.
Aby uzyskać informacje o bibliotece klienta wpisów tajnych, zobacz Biblioteka klienta wpisów tajnych.
Aby uzyskać informacje o bibliotece klienta certyfikatów, zobacz Biblioteka klienta certyfikatów.

Współtworzenie

Zobacz CONTRIBUTING.md , aby uzyskać szczegółowe informacje na temat kompilowania, testowania i współtworzenia tych bibliotek.

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Wrażenia

Udostępnij przez