Szybki start: biblioteka klienta zarządzanego HSM Azure Key Vault dla .NET

Rozpocznij pracę z biblioteką klienta usługi Managed HSM Azure Key Vault dla .NET. Kompleksowo zarządzany HSM to w pełni zarządzana, wysoce dostępna, jednostanowa usługa w chmurze zgodna ze standardami, która umożliwia ochronę kluczy kryptograficznych dla aplikacji w chmurze przy użyciu modułów HSM zweryfikowanych według standardu FIPS 140-3 poziomu 3. Aby uzyskać więcej informacji na temat zarządzanego modułu HSM, zapoznaj się z omówieniem.

Z tego przewodnika Szybki start dowiesz się, jak uzyskiwać dostęp do kluczy i wykonywać operacje kryptograficzne w zarządzanym module HSM przy użyciu biblioteki klienta .NET.

Zasoby biblioteki klienta zarządzanego modułu HSM:

dokumentacja referencyjna API | kod źródłowy | Pakiet (NuGet)

Wymagania wstępne

Konfigurowanie środowiska lokalnego

W tym szybkim starcie użyto biblioteki Azure Identity z Azure CLI do uwierzytelniania usług na platformie Azure. Deweloperzy mogą również używać Visual Studio lub Visual Studio Code do uwierzytelniania wywołań. Aby uzyskać więcej informacji, zobacz Uwierzytelnij klienta za pomocą biblioteki Client Azure Identity.

Zaloguj się do Azure

Uruchom polecenie , az login aby się zalogować:

az login

Tworzenie nowej aplikacji konsolowej .NET

  1. W powłoce poleceń uruchom następujące polecenie, aby utworzyć projekt o nazwie mhsm-console-app:

    dotnet new console --name mhsm-console-app

  2. Przejdź do nowo utworzonego katalogu mhsm-console-app :

    cd mhsm-console-app

Instalowanie pakietów

Zainstaluj biblioteki klienta Azure Identity i Key Vault Keys:

dotnet add package Azure.Identity
dotnet add package Azure.Security.KeyVault.Keys

Tworzenie przykładowego kodu

Zastąp zawartość Program.cs pliku następującym kodem. Zastąp <hsm-name> nazwą zarządzanego HSM i <key-name> istniejącą nazwą klucza.

using Azure.Identity;
using Azure.Security.KeyVault.Keys;
using Azure.Security.KeyVault.Keys.Cryptography;

// Use DefaultAzureCredential for automatic credential selection
// Works with managed identities in Azure, and developer credentials locally
var credential = new DefaultAzureCredential();

// Connect to Managed HSM - replace with your HSM URI
var hsmUri = new Uri("https://<hsm-name>.managedhsm.azure.net");
var keyClient = new KeyClient(hsmUri, credential);

// Get a key reference
string keyName = "<key-name>";
Console.WriteLine($"Retrieving key '{keyName}' from Managed HSM...");
KeyVaultKey key = await keyClient.GetKeyAsync(keyName);
Console.WriteLine($"Key retrieved. Key type: {key.KeyType}");

// Perform cryptographic operations
var cryptoClient = new CryptographyClient(key.Id, credential);

// Encrypt data
byte[] plaintext = System.Text.Encoding.UTF8.GetBytes("Hello, Managed HSM!");
Console.WriteLine($"\nOriginal text: {System.Text.Encoding.UTF8.GetString(plaintext)}");

EncryptResult encryptResult = await cryptoClient.EncryptAsync(EncryptionAlgorithm.RsaOaep256, plaintext);
Console.WriteLine($"Encrypted (base64): {Convert.ToBase64String(encryptResult.Ciphertext)}");

// Decrypt data
DecryptResult decryptResult = await cryptoClient.DecryptAsync(EncryptionAlgorithm.RsaOaep256, encryptResult.Ciphertext);
Console.WriteLine($"Decrypted text: {System.Text.Encoding.UTF8.GetString(decryptResult.Plaintext)}");

Console.WriteLine("\nDone!");

Uruchamianie aplikacji

Uruchom aplikację za pomocą polecenia dotnet run.

dotnet run

Powinny zostać wyświetlone dane wyjściowe podobne do następujących:

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (base64): <encrypted-data>
Decrypted text: Hello, Managed HSM!

Done!

Omówienie kodu

Uwierzytelnianie przy użyciu DefaultAzureCredential

DefaultAzureCredential automatycznie wybiera odpowiednie poświadczenie na podstawie środowiska:

Środowisko Używane poświadczenia
Azure VMs, App Service, Funkcje Tożsamość zarządzana przypisana przez system lub przypisana przez użytkownika
Azure Kubernetes Service Tożsamość zadania
Rozwój lokalny Azure CLI, Visual Studio lub poświadczenia programu VS Code
Potoki CI/CD Federacja tożsamości obciążenia lub jednostka usługi

Poświadczenie sprawdza te źródła w następującej kolejności:

  1. Zmienne środowiskowe
  2. Tożsamość zadania
  3. Tożsamość zarządzana
  4. Azure CLI
  5. Azure PowerShell
  6. Visual Studio / VS Code poświadczenia

W przypadku obciążeń produkcyjnych w Azure tożsamości zarządzane są zdecydowanie zalecane, ponieważ całkowicie eliminują zarządzanie poświadczeniami.

Kluczowe operacje

Klasa KeyClient udostępnia metody:

  • Tworzenie, pobieranie, aktualizowanie i usuwanie kluczy
  • Lista kluczy i wersji kluczy
  • Tworzenie kopii zapasowych i przywracanie kluczy

Klasa CryptographyClient udostępnia operacje kryptograficzne:

  • Szyfrowanie i odszyfrowywanie danych
  • Podpisywanie i weryfikowanie podpisów
  • Zawijanie i odpakowywanie kluczy

Przypisywanie ról zarządzanego modułu HSM

Aby aplikacja mogła uzyskiwać dostęp do kluczy, przypisz odpowiednią lokalną rolę RBAC zarządzanego modułu HSM do tożsamości zarządzanej. Zastąp <vm-name>, <resource-group> i <hsm-name> rzeczywistymi wartościami.

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name <hsm-name> \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

Aby uzyskać więcej informacji na temat ról i uprawnień, zobacz Zarządzanie lokalnymi rolami RBAC modułu HSM.

Uprzątnij zasoby

Gdy grupa zasobów i wszystkie powiązane zasoby nie będą już potrzebne, usuń je:

az group delete --name <resource-group>

Ostrzeżenie

Usunięcie grupy zasobów powoduje przełączenie zarządzanego modułu HSM do stanu usunięcia nietrwałego. Zarządzany moduł HSM będzie nadal rozliczany, dopóki nie zostanie usunięty. Zobacz Nietrwałe usuwanie zarządzanego modułu HSM i ochrona przed przeczyszczaniem

Następne kroki

  • Ostatnia aktualizacja o