Szybki start: tworzenie pierwszego klucza zewnętrznego przy użyciu Azure CLI

W tym przewodniku Szybki start połączysz zewnętrzny moduł HSM z zarządzanym modułem HSM, utworzysz odwołanie do klucza zewnętrznego i przetestujesz ścieżkę ochrony kluczy. Następnie użyjesz identyfikatora URI klucza zarządzanego przez moduł HSM, aby skonfigurować szyfrowanie danych magazynowanych z użyciem klucza zarządzanego przez klienta (CMK) w zgodnej usłudze Azure.

Aby uzyskać informacje o modelu szyfrowania i zgodności usługi, zobacz Co to jest zarządzanie kluczami zewnętrznymi dla Managed HSM?

Jeśli wolisz korzystać z portalu Azure, zobacz Szybki start: tworzenie pierwszego klucza zewnętrznego przy użyciu portalu Azure.

Prerequisites

Przed rozpoczęciem potrzebne są następujące elementy:

Zaloguj się do Azure

az login

Ustaw subskrypcję, jeśli masz więcej niż jedną:

az account set --subscription "<subscription-id>"

Pokaż certyfikat klienta zarządzanego modułu HSM

Zarządzany moduł HSM przedstawia certyfikat klienta X.509 serwerowi proxy EKM na każdym przychodzącym połączeniu wzajemnego protokołu TLS (mTLS). Przed utworzeniem połączenia z zewnętrznym systemem zarządzania kluczami pobierz nazwę pospolitą (CN) podmiotu certyfikatu oraz certyfikat głównego urzędu certyfikacji, a następnie dodaj je do listy dozwolonych na serwerze proxy. Dzięki temu serwer proxy sprawdzi, czy połączenie pochodzi z Managed HSM, a nie od dowolnego wywołującego.

az keyvault ekm-connection certificate show --hsm-name <Managed HSM Name>

Dane wyjściowe wyglądają mniej więcej tak:

{
  "caCertificates": [
    "MIIDj...<truncated>...MrY="
  ],
  "subjectCommonName": "contoso.managedhsmclient.azure.net"
}

Skonfiguruj serwer proxy tak, aby ufał połączeniom, które przedstawiają certyfikat zawierający subjectCommonName i zakorzeniony w jednym z certyfikatów z powyższej listy caCertificates. Dokładne kroki zależą od dostawcy serwera proxy.

Note

Aby uzyskać szczegółowe informacje o etapach rotacji i cyklu życia certyfikatu, zobacz Konfigurowanie sieci i mTLS na potrzeby zarządzania kluczami zewnętrznymi w usłudze Managed HSM.

Utwórz połączenie z zewnętrznym systemem zarządzania kluczami

Połączenie zarządzania kluczami zewnętrznymi wiąże zarządzany moduł HSM z pojedynczym serwerem proxy EKM. Zawiera adres serwera proxy, zaufany certyfikat główny CA serwera oraz opcjonalny prefiks ścieżki.

Ta sekcja tworzy publiczne połączenie internetowe. W przypadku Private Link postępuj zgodnie z instrukcjami Configure the Azure Private Link model (preview), a następnie przejdź do Verify the connection.

az keyvault ekm-connection create \
    --hsm-name <Managed HSM Name> \
    --host <EKMProxy Host> \
    --server-ca-certificate <Root cert> \
    [--path-prefix <prefix>]

Opis parametrów:

  • --hsm-name: Nazwa Twojego zarządzanego modułu HSM.
  • --host: w pełni kwalifikowana nazwa hosta serwera proxy EKM. Na przykład proxy.contoso.com. Serwer proxy musi nasłuchiwać na porcie TCP 443; port niestandardowy nie jest obsługiwany.
  • --server-ca-certificate: Określa ścieżkę do pliku certyfikatu głównego urzędu certyfikacji w formacie PEM lub DER, używanego do weryfikacji certyfikatu TLS serwera proxy.
  • --path-prefix (opcjonalnie): prefiks ścieżki URL, jeśli serwer proxy multipleksuje wielu klientom lub grupom według ścieżki. Na przykład /contoso/prod.

Note

Przekaż certyfikat głównego urzędu certyfikacji do --server-ca-certificate, a nie certyfikat liścia serwera proxy. Zarządzany moduł HSM używa tego urzędu certyfikacji do weryfikowania całego łańcucha certyfikatów przekazanego przez serwer proxy podczas uzgadniania połączenia mTLS. Przekazanie certyfikatu liścia powoduje niepowodzenie uzgadniania w przypadku każdego odnowienia certyfikatu.

Weryfikowanie połączenia

Po utworzeniu połączenia sprawdź, czy zarządzany moduł HSM może nawiązać połączenie z serwerem proxy:

az keyvault ekm-connection check --hsm-name <Managed HSM Name>

To polecenie wywołuje punkt końcowy serwera proxy /info za pośrednictwem skonfigurowanego połączenia. Prawidłowy wynik wygląda następująco:

{
  "apiVersion": "1.0",
  "ekmProduct": "Contoso HSM v1.0.0",
  "ekmVendor": "Contoso HSM",
  "proxyName": "Contoso Proxy Service",
  "proxyVendor": "Contoso Proxy"
}

Typowe przyczyny awarii obejmują reguły zapory blokujące port serwera proxy, nieprawidłową wartość --host lub odrzucenie przez serwer proxy certyfikatu klienta usługi Managed HSM. Aby uzyskać instrukcje korygowania, zobacz Rozwiązywanie problemów z zarządzaniem kluczami zewnętrznymi zarządzanego modułu HSM.

Tworzenie klucza zewnętrznego

Utwórz odwołanie do klucza w usłudze Managed HSM, które wskazuje na klucz zewnętrzny w module HSM. Zarządzany moduł HSM nie generuje żadnego materiału kluczowego. To polecenie rejestruje odwołanie do istniejącego klucza zidentyfikowanego przez jego identyfikator klucza zewnętrznego.

az keyvault key create \
    --external-key-id <external-key-identifier> \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

Opis parametrów:

  • --external-key-id: identyfikator klucza zewnętrznego zarejestrowany na serwerze proxy. Jest to identyfikator używany przez serwer proxy do wyszukiwania poprawnego klucza w zewnętrznym module HSM.
  • --hsm-name: Nazwa Twojego zarządzanego modułu HSM.
  • --name: Nazwa, którą chcesz nadać odwołaniu do klucza zarządzanego modułu HSM. Staje się to częścią identyfikatora URI klucza używanego przez usługi platformy Azure.

Important

Identyfikator klucza zewnętrznego jest niezmienny przez okres istnienia wersji klucza. Nie można go zmienić po utworzeniu. Aby przeprowadzić rotację klucza, utwórz nową wersję klucza z nowym identyfikatorem klucza zewnętrznego za pomocą az keyvault key create z tym samym --name. Identyfikator URI klucza (identyfikator URI modułu HSM i nazwa klucza) pozostaje stabilny w różnych wersjach; tylko segment wersji ulega zmianie.

Polecenie zwraca URI klucza w postaci https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Zachowaj ten identyfikator URI do konfigurowania usługi Azure.

Weryfikowanie zawijania/odpakowywanie

Przetestuj ścieżkę ochrony klucza za pomocą operacji wrap i unwrap w obie strony. Zewnętrzny moduł HSM wykonuje operacje za pośrednictwem serwera proxy, a Managed HSM zwraca wynik. Ten test potwierdza, że ścieżka dostępu działa. Nie konfiguruje ani nie sprawdza poprawności integracji usługi Azure z CMK.

Note

Użyj punktów końcowych płaszczyzny danych wrapkey i az rest z unwrapkey dla tego testu. az keyvault key encrypt wywołuje inną operację interfejsu API klucza i nie zastępuje opakowywania klucza szyfrowania danych.

  1. Utwórz treść żądania dla operacji zawijania. Ustaw value na materiał klucza zakodowany w formacie base64url, który chcesz opakować.

    {
  "alg": "RSA-OAEP-256",
  "value": "<base64url-encoded-plaintext-key>"
}

    Zapisz go jako wrapkey.json. W przypadku kluczy zewnętrznych AES użyj polecenia "alg": "A256KW" zamiast RSA-OAEP-256.

  2. Wywołaj punkt końcowy wrapkey w odwołaniu do klucza:

    az rest --method POST \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/wrapkey?api-version=7.5" \
    --resource "https://managedhsm.azure.net" \
    --headers "Content-Type=application/json" \
    --body @wrapkey.json

    Odpowiedź zwraca wersję klucza (kid) i value pole zawierające zakodowany w formacie base64url klucz opakowany. Skopiuj element value dla następnego kroku.

  3. Utwórz treść żądania dla operacji odpakowania przy użyciu zawiniętego value z poprzedniego kroku:

    {
  "alg": "RSA-OAEP-256",
  "value": "<wrapped-value-from-previous-step>"
}

    Zapisz go jako unwrapkey.json.

  4. Wywołaj punkt końcowy unwrapkey, aby potwierdzić poprawność operacji w obie strony:

    az rest --method POST \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/unwrapkey?api-version=7.5" \
    --resource "https://managedhsm.azure.net" \
    --headers "Content-Type=application/json" \
    --body @unwrapkey.json

    Pomyślna odpowiedź zwraca oryginalny zwykły tekst value opakowany w pierwszym kroku. Jeśli operacja unwrap się nie powiedzie, zobacz Rozwiązywanie problemów z zewnętrznym zarządzaniem kluczami zarządzanego modułu HSM, aby uzyskać informacje o kodach błędów serwera proxy oraz krokach naprawczych.

Użyj klucza z usługą Azure

Ukończ integrację obciążenia roboczego, postępując zgodnie z dokumentacją konfiguracji CMK usługi Azure:

  1. Upewnij się, że usługa obsługuje klucze CMK obsługiwane przez usługę Managed HSM oraz że typ i algorytm klucza zewnętrznego spełniają jej wymagania.
  2. Udziel tożsamości używanej przez usługę wymaganych lokalnych uprawnień RBAC zarządzanego modułu HSM. Aby uzyskać wskazówki dotyczące przypisywania ról, zobacz Managed HSM access control.
  3. Skonfiguruj ustawienia CMK usługi przy użyciu identyfikatora URI klucza usługi Managed HSM. Użyj formatu URI z wersją lub bez wersji wymaganego przez tę usługę. W przypadku usługi Azure Storage zobacz Konfigurowanie kluczy zarządzanych przez klienta przy użyciu Azure Key Vault Managed HSM.
  4. Upewnij się, że usługa zgłasza oczekiwaną konfigurację CMK, a następnie wykonaj operację odczytu/zapisu w chronionym obciążeniu roboczym. Przejrzyj diagnostykę usługi i dzienniki zarządzania kluczami zewnętrznymi Managed HSM, jeśli operacja zakończy się niepowodzeniem.

Usługa Azure korzysta z istniejącej integracji z usługą Managed HSM. Nie potrzebuje interfejsu API ani poświadczeń specyficznych dla dostawcy Twojego zewnętrznego modułu HSM.

Wyświetlanie dzienników inspekcji

Każde wywołanie serwera proxy EKM powoduje utworzenie wpisu EkmProxyOperation w dziennikach diagnostycznych usługi Managed HSM. Aby wykonać zapytanie w Log Analytics:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.KEYVAULT"
| where OperationName contains "Ekm"
| project TimeGenerated, Resource, OperationName, requestUri_s, ResultType, ResultDescription

Dziennik zawiera typ operacji (opakowywanie lub odpakowywanie), identyfikator klucza zewnętrznego, kod stanu HTTP zwrócony przez serwer proxy oraz opóźnienie połączenia w obie strony. Pełny przewodnik dotyczący rejestrowania i monitorowania, w tym konfiguracji alertów i korelowania dzienników po stronie serwera proxy, znajduje się w dokumencie Rejestrowanie i monitorowanie zarządzania kluczami zewnętrznymi dla usługi Managed HSM.

Uprzątnij zasoby

Jeśli skonfigurowano usługę Azure do używania tego klucza, należy przeprowadzić migrację obciążenia do innego klucza przed usunięciem odwołania lub połączenia. Zachowaj klucz zewnętrzny i jego połączenie tak długo, jak wymagają tego dane, kopie zapasowe lub migawki obciążenia.

Aby usunąć zasoby utworzone w tym przewodniku Szybki start:

  1. Usuń odwołanie do klucza usługi Managed HSM:

    az keyvault key delete \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

  2. Usuń połączenie zarządzania kluczami zewnętrznymi:

    az keyvault ekm-connection delete \
    --hsm-name <Managed HSM Name>

Usunięcie odwołania do zarządzanego klucza HSM nie wpływa na materiał klucza w zewnętrznym module HSM. Ten klucz pozostaje w Twoim module HSM, dopóki go stamtąd nie usuniesz.

Następne kroki

  • Ostatnia aktualizacja o