Szybki start: tworzenie pierwszego klucza zewnętrznego przy użyciu Azure CLI (wersja zapoznawcza)

Important

Zarządzanie kluczami zewnętrznymi dla usługi Managed HSM jest w wersji zapoznawczej. Funkcje w wersji zapoznawczej są udostępniane Użytkownikowi pod warunkiem, że zgadzasz się na dodatkowe warunki użytkowania. Niektóre aspekty tej funkcji mogą ulec zmianie przed ogólną dostępnością.

W tym przewodniku Szybki start zarejestrujesz połączenie serwera proxy EKM z zarządzanym modułem HSM, a następnie utworzysz odwołanie do zarządzanego klucza HSM wskazującego klucz w module HSM obsługiwanym przez klienta. Na końcu uruchomisz rundę zawijania/odpakowania, aby potwierdzić, że integracja działa.

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:

  • Istniejący zarządzany moduł HSM wdrożony w dowolnym publicznym regionie platformy Azure, z włączoną dla subskrypcji funkcją zarządzania kluczami zewnętrznymi przez zespół Microsoft odpowiedzialny za Twoje konto. Skontaktuj się z zespołem ds. kont, aby poprosić o włączenie. Aby utworzyć zarządzany moduł HSM, zobacz Szybki start: aprowizuj i aktywuj zarządzany moduł HSM przy użyciu Azure CLI.
  • Operacyjny serwer proxy EKM osiągalny z Azure. Serwer proxy musi zaimplementować specyfikację interfejsu API serwera proxy EKM. Informacje o obsługiwanych dostawcach można znaleźć tutaj: Co to jest zarządzanie kluczami zewnętrznymi w usłudze Managed HSM?.
  • Klucz utworzony w zewnętrznym module HSM, ze znanym identyfikatorem klucza zewnętrznego. Identyfikator klucza zewnętrznego to identyfikator używany przez serwer proxy do wyszukania klucza.
  • Certyfikat głównego urzędu certyfikacji (format PEM), który podpisał certyfikat serwera proxy protokołu TLS.
  • Azure CLI w wersji 2.x z zainstalowanym najnowszym keyvault rozszerzeniem. Uruchom polecenie az extension add --name keyvault lub az extension update --name keyvault , aby pobrać najnowszą wersję.
  • Rola Managed HSM EKM Administrator do zarządzania połączeniami z zewnętrznymi systemami zarządzania kluczami oraz rola Managed HSM Crypto User do tworzenia i używania kluczy. Aby zapoznać się z krokami przypisywania ról, zobacz Managed HSM access control (Zarządzana kontrola dostępu modułu HSM).

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. W ten sposób serwer proxy sprawdza, czy połączenie pochodzi z zarządzanego modułu HSM — a nie z dowolnego obiektu 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.

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 w wersji zapoznawczej.
  • --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. W usłudze Managed HSM nie jest generowany żaden materiał kluczowy — to polecenie rejestruje referencję do istniejącego klucza identyfikowanego za pomocą jego zewnętrznego identyfikatora klucza.

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>. Użyj tego identyfikatora URI podczas konfigurowania ustawień klucza zarządzanego przez klienta (CMK) w usługach Azure.

Weryfikowanie zawijania/odpakowywanie

Potwierdź integrację od końca do końca za pomocą cyklu opakowania i rozpakowania. Rzeczywiste operacje opakowywania i odpakowywania są realizowane przez Twój serwer proxy i zewnętrzny moduł HSM — Managed HSM kieruje żądanie i zwraca wynik.

Important

Nie używaj az keyvault key encrypt do testowania klucza zewnętrznego. To polecenie wykonuje operację encrypt, której zewnętrzne zarządzanie kluczami nie obsługuje — zewnętrzne zarządzanie kluczami obsługuje tylko wrapKey i unwrapKey. Zamiast tego wywołaj bezpośrednio punkty końcowe płaszczyzny danych wrapkey i unwrapkey za pomocą az rest.

  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.

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

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

  • Last updated on