Biblioteka klienta administracji usługi Azure KeyVault dla platformy .NET — wersja 4.3.0

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.

Klienci biblioteki administracyjnej usługi Azure Key Vault obsługują zadania administracyjne, takie jak pełna kopia zapasowa/przywracanie i kontrola dostępu oparta na rolach (RBAC) na poziomie klucza.

Kod | źródłowy Pakiet (NuGet) | Dokumentacja | produktu Próbki

Wprowadzenie

Instalowanie pakietu

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

dotnet add package Azure.Security.KeyVault.Administration

Wymagania wstępne

• Subskrypcja platformy Azure.
• Istniejąca usługa Azure Key Vault. Jeśli musisz utworzyć Key Vault platformy Azure, możesz użyć 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.

Aby utworzyć 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 klas klienta poniżej. 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 deweloperskich i produkcyjnych. 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

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:

• Co najmniej 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 3 certyfikatów z podpisem własnym.

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

Kontrolowanie dostępu do zarządzanego modułu HSM

Wyznaczeni administratorzy przypisani podczas tworzenia są automatycznie dodawani do wbudowanej roli "Administratorzy zarządzanego modułu HSM", którzy mogą pobrać domenę zabezpieczeń i zarządzać rolami dostępu do płaszczyzny danych, między innymi ograniczonymi uprawnieniami.

Aby wykonać inne akcje dotyczące kluczy, należy przypisać podmioty zabezpieczeń do innych ról, takich jak "Zarządzany użytkownik kryptograficzny modułu HSM", który może wykonywać niedestrukcyjne operacje klucza:

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>

Przeczytaj najlepsze rozwiązania dotyczące prawidłowego zabezpieczania zarządzanego modułu HSM.

Tworzenie obiektu KeyVaultAccessControlClient

Utwórz wystąpienie elementu DefaultAzureCredential , aby przekazać element do elementu KeyVaultAccessControlClient. 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.

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

Tworzenie elementu KeyVaultBackupClient

Utwórz wystąpienie elementu DefaultAzureCredential , aby przekazać element do elementu KeyVaultBackupClient. 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.

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

Tworzenie elementu KeyVaultSettingClient

Utwórz wystąpienie elementu DefaultAzureCredential , aby przekazać element do elementu KeyVaultSettingsClient. 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.

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

Kluczowe pojęcia

KeyVaultRoleDefinition

A KeyVaultRoleDefinition to kolekcja uprawnień. Definicja roli definiuje operacje, które można wykonać, takie jak odczyt, zapis i usuwanie. Może również definiować operacje wykluczone z dozwolonych operacji.

KeyVaultRoleDefinitions można wymienić i określić jako część KeyVaultRoleAssignmentelementu .

KeyVaultRoleAssignment

A KeyVaultRoleAssignment jest skojarzeniem klucza KeyVaultRoleDefinition z jednostką usługi. Można je tworzyć, wyświetlać, pobierać pojedynczo i usuwać.

KeyVaultAccessControlClient

Element zapewnia KeyVaultAccessControlClient zarówno operacje synchroniczne, jak i asynchroniczne umożliwiające zarządzanie obiektami KeyVaultRoleDefinition i KeyVaultRoleAssignment .

KeyVaultBackupClient

Element zapewnia KeyVaultBackupClient zarówno operacje synchroniczne, jak i asynchroniczne na potrzeby wykonywania pełnych kopii zapasowych kluczy, przywracania pełnego klucza i selektywnych przywracania kluczy.

BackupOperation

Element BackupOperation reprezentuje długotrwałą operację tworzenia pełnej kopii zapasowej klucza.

RestoreOperation

A RestoreOperation reprezentuje długotrwałą operację zarówno dla pełnego klucza, jak i selektywnego przywracania klucza.

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

Opcje | klienta Uzyskiwanie dostępu do odpowiedzi | Długotrwałe operacje | Obsługa błędów | Diagnostyka | Szyderczy | Okres istnienia klienta

Przykłady

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

Poniższa sekcja zawiera kilka fragmentów kodu, które zostały client utworzone powyżej dla klientów kontroli dostępu lub kopii zapasowych, obejmujące niektóre z najbardziej typowych zadań związanych z kontrolą dostępu w usłudze Azure Key Vault:

Przykłady synchronizacji

• Kontrola dostępu
  • Wyświetlanie listy wszystkich definicji ról
  • Wyświetlanie listy wszystkich przypisań ról
  • Tworzenie przypisania roli
  • Uzyskiwanie przypisania roli
  • Usuwanie przypisania roli
• Tworzenie kopii zapasowej i przywracanie
  • Wykonywanie pełnej kopii zapasowej klucza
  • Wykonywanie pełnego przywracania klucza

Przykłady asynchroniczne

• Kontrola dostępu
  • Wyświetlanie listy wszystkich definicji ról
  • Wyświetlanie listy wszystkich przypisań ról
  • Tworzenie przypisania roli
  • Uzyskiwanie przypisania roli
  • Usuwanie przypisania roli
• Tworzenie kopii zapasowej i przywracanie
  • Wykonywanie pełnej kopii zapasowej klucza
  • Wykonywanie pełnego przywracania klucza

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ą Azure Key Vault Administration przy użyciu zestawu SDK platformy .NET błędy zwracane przez usługę odpowiadają tym samym kodom stanu HTTP zwracanym dla żądań interfejsu API REST.

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

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

Konfigurowanie rejestrowania konsoli

Najprostszym sposobem wyświetlenia dzienników jest włączenie rejestrowania konsoli. Aby utworzyć odbiornik dziennika zestawu Azure SDK, który generuje komunikaty do konsoli, użyj AzureEventSourceListener.CreateConsoleLogger metody .

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

Aby dowiedzieć się więcej na temat innych mechanizmów rejestrowania, zobacz tutaj.

Następne kroki

Rozpocznij pracę z naszymi przykładami.

Współtworzenie

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.

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.