Schnellstart: Erstellen Des ersten externen Schlüssels mithilfe des Azure CLI (Vorschau)

Wichtig

Die externe Schlüsselverwaltung des verwaltete HSM ist in der Vorschauversion. Vorschaufeatures werden Ihnen unter der Bedingung zur Verfügung gestellt, dass Sie den ergänzenden Nutzungsbedingungen zustimmen. Einige Aspekte dieses Features können sich vor der allgemeinen Verfügbarkeit ändern.

In dieser Schnellstartanleitung registrieren Sie eine EKM-Proxyverbindung mit Ihrem verwalteten HSM und erstellen dann einen verwalteten HSM-Schlüsselverweis, der auf einen Schlüssel in Ihrem vom Kunden betriebenen HSM verweist. Am Ende führen Sie einen Wrap/Unwrap-Roundtrip durch, um zu überprüfen, ob die Integration funktioniert.

Wenn Sie lieber das Azure-Portal verwenden möchten, lesen Sie die Schnellstartanleitung: Erstellen Des ersten externen Schlüssels mithilfe des Azure Portals.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

  • Ein vorhandenes verwaltetes HSM, das in einer beliebigen öffentlichen Azure-Region bereitgestellt wurde und bei dem die Verwaltung externer Schlüssel für das Abonnement von Ihrem Microsoft-Konto aktiviert wurde. Team Wenden Sie sich an Ihr Kontoteam, um die Aktivierung anzufordern. Informationen zum Erstellen eines verwalteten HSM finden Sie in der Schnellstartanleitung: Bereitstellen und Aktivieren eines verwalteten HSM mithilfe von Azure CLI.
  • Ein betriebsbereiter EKM-Proxy, der von Azure aus erreichbar ist. Der Proxy muss die EKM-Proxy-API-Spezifikation implementieren. Informationen zu unterstützten Anbietern finden Sie unter Was ist die Verwaltung von externen HSM-Schlüsseln?.
  • Ein schlüssel, der in Ihrem externen HSM mit einem bekannten bezeichner für externe Schlüssel erstellt wurde. Der Bezeichner des externen Schlüssels ist der Bezeichner, den Ihr Proxy zum Nachschlagen des Schlüssels verwendet.
  • Das Root-CA-Zertifikat (PEM-Format), das das TLS-Serverzertifikat Ihres Proxys signiert hat.
  • Azure CLI Version 2.x mit der neuesten installierten keyvault Erweiterung. Führen Sie az extension add --name keyvault oder az extension update --name keyvault aus, um die neueste Version zu erhalten.
  • Die Managed HSM EKM Administrator Rolle zum Verwalten externer Schlüsselverwaltungsverbindungen und die Managed HSM Crypto User Rolle zum Erstellen und Verwenden von Schlüsseln. Informationen zu Rollenzuweisungsschritten finden Sie unter Verwaltete HSM-Zugriffssteuerung.

Anmelden bei Azure

az login

Legen Sie Ihr Abonnement fest, wenn Sie mehrere haben:

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

Anzeigen des verwalteten HSM-Clientzertifikats

Managed HSM legt Ihrem EKM-Proxy bei jeder eingehenden mTLS-Verbindung ein X.509-Clientzertifikat vor. Rufen Sie vor dem Erstellen der Verbindung zur externen Schlüsselverwaltung den Common Name (CN) des Zertifikatssubjekts und das Stammzertifikat der Zertifizierungsstelle ab und setzen Sie diese auf Ihrem Proxy auf die Zulassungsliste. So überprüft der Proxy, ob die Verbindung von Ihrem verwalteten HSM stammt , nicht von einem beliebigen Aufrufer.

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

Die Ausgabe sieht etwa so aus:

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

Konfigurieren Sie Ihren Proxy so, dass er Verbindungen vertraut, die ein Zertifikat mit dem subjectCommonName vorlegen und deren Vertrauenskette auf eines der Zertifikate in der obigen Liste caCertificates zurückgeht. Die genauen Schritte hängen von Ihrem Proxyanbieter ab.

Hinweis

Informationen zu den Rotationsschritten und Details zum Zertifikatslebenszyklus finden Sie unter Netzwerkkonfiguration und mTLS für die externe Schlüsselverwaltung für Managed HSM konfigurieren.

Erstellen Sie die Verbindung zur externen Schlüsselverwaltung

Die Verbindung zur Verwaltung externer Schlüssel bindet Ihr verwaltetes HSM an einen einzelnen EKM-Proxy. Sie enthält die Proxyadresse, den Vertrauensanker der Serverzertifizierungsstelle und ein optionales Pfadpräfix.

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

Parameterverweis:

  • --hsm-name: Der Name Ihres Managed HSM.
  • --host: Der vollqualifizierte Hostname Ihres EKM-Proxys. Beispiel: proxy.contoso.com Der Proxy muss auf TCP-Port 443 lauschen; Ein nicht standardmäßiger Port wird in der Vorschau nicht unterstützt.
  • --server-ca-certificate: Gibt den Pfad zur Zertifikatdatei der Stammzertifizierungsstelle (PEM oder DER-Format) an, die zum Überprüfen des TLS-Serverzertifikats des Proxys verwendet wird.
  • --path-prefix (optional): Ein URL-Pfadpräfix, wenn Ihr Proxy mehrere Kunden oder Pools über den Pfad bündelt. Beispiel: /contoso/prod

Hinweis

Übergeben Sie das Zertifikat der Stammzertifizierungsstelle an --server-ca-certificate, nicht an das Blattzertifikat des Proxys. Managed HSM verwendet diese Zertifizierungsstelle, um die vollständige Zertifikatskette zu validieren, die von Ihrem Proxy während des mTLS-Handshakes vorgelegt wird. Das Übergeben des Blattzertifikats stattdessen führt dazu, dass der Handshake für eine Zertifikatverlängerung fehlschlägt.

Die Verbindung prüfen

Überprüfen Sie nach dem Erstellen der Verbindung, ob verwaltetes HSM Ihren Proxy erreichen kann:

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

Dieser Befehl ruft den Endpunkt des Proxys /info über die konfigurierte Verbindung auf. Eine erfolgreiche Ausgabe sieht etwa so aus:

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

Häufige Fehlerursachen sind Firewallregeln, die den Proxyport blockieren, einen falschen --host Wert oder den Proxy, der das verwaltete HSM-Clientzertifikat ablehnt. Informationen zu Schritten zur Problembehebung finden Sie unter Problembehandlung für die Verwaltung externer Schlüssel in Managed HSM.

Erstellen des externen Schlüssels

Erstellen Sie einen verwalteten HSM-Schlüsselverweis, der auf den externen Schlüssel in Ihrem HSM verweist. In verwaltetem HSM wird kein Schlüsselmaterial generiert. Dieser Befehl registriert einen Verweis auf einen vorhandenen Schlüssel, der durch seinen externen Schlüsselbezeichner identifiziert wird.

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

Parameterverweis:

  • --external-key-id: Die bei Ihrem Proxy registrierte Kennung des externen Schlüssels. Dies ist der Bezeichner, den der Proxy verwendet, um den richtigen Schlüssel in Ihrem externen HSM nachzuschlagen.
  • --hsm-name: Der Name Ihres Managed HSM.
  • --name: Der Name, den Sie dem verwalteten HSM-Schlüsselverweis zuweisen möchten. Dies wird Teil der Schlüssel-URI, die die Azure-Dienste verwenden.

Wichtig

Die ID des externen Schlüssels ist für die Lebensdauer einer Schlüsselversion unveränderlich . Sie können sie nach der Erstellung nicht mehr ändern. Um den Schlüssel zu rotieren, erstellen Sie eine neue Schlüsselversion mit einem neuen externen Schlüsselbezeichner unter Verwendung von az keyvault key create mit demselben --name. Der Schlüssel-URI (HSM-URI + Schlüsselname) bleibt über Versionen hinweg stabil; nur das Versionssegment ändert sich.

Der Befehl gibt den Schlüssel-URI im Formular https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>zurück. Verwenden Sie diesen URI beim Konfigurieren von CMK-Einstellungen (Customer Managed Key) in Azure-Diensten.

Wrap/Unwrap überprüfen

Bestätigen Sie die End-to-End-Integration mit einem Wrap-/Unwrap-Roundtrip. Die eigentlichen Wrap- und Unwrap-Vorgänge werden bei Ihrem Proxy und externen HSM durchgeführt – Managed HSM leitet die Anforderung weiter und gibt das Ergebnis zurück.

Wichtig

Verwenden Sie az keyvault key encrypt nicht, um einen externen Schlüssel zu testen. Dieser Befehl führt einen encrypt-Vorgang aus, der von der externen Schlüsselverwaltung nicht unterstützt wird — die externe Schlüsselverwaltung unterstützt nur wrapKey und unwrapKey. Rufen Sie stattdessen die Endpunkte wrapkey und unwrapkey der Datenebene direkt mit az rest auf.

  1. Erstellen Sie einen Anforderungstext für den Wrap-Vorgang. Legen Sie den Wert von value auf das base64url-kodierte Schlüsselmaterial fest, das Sie wrappen möchten.

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

    Speichern Sie es als wrapkey.json. Verwenden Sie "alg": "A256KW" für externe AES-Schlüssel anstelle von RSA-OAEP-256.

  2. Rufen Sie den wrapkey Endpunkt in Ihrem Schlüsselverweis auf:

    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

    Die Antwort gibt die Schlüsselversion (kid) und ein value Feld zurück, das den base64url-codierten umschlossenen Schlüssel enthält. Kopieren Sie das value für den nächsten Schritt.

  3. Erstellen Sie einen Anforderungstext für den Unwrap-Vorgang, indem Sie den verpackten value aus dem vorherigen Schritt verwenden:

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

    Speichern Sie es als unwrapkey.json.

  4. Rufen Sie den unwrapkey-Endpunkt auf, um die Korrektheit der Roundtrip-Verarbeitung zu bestätigen:

    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

    Eine erfolgreiche Antwort gibt den ursprünglichen Klartext value zurück, den Sie im ersten Schritt eingeschlossen haben. Wenn das Entpacken fehlschlägt, lesen Sie die Problembehandlung für die Verwaltung verwalteter HSM-externer Schlüssel für Proxyfehlercodes und Korrekturschritte.

Auditprotokolle anzeigen

Jeder EKM-Proxyaufruf erzeugt einen EkmProxyOperation Eintrag in Ihren verwalteten HSM-Diagnoseprotokollen. So fragen Sie diese in Log Analytics ab:

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

Das Protokoll enthält den Vorgangstyp (wrap oder unwrap), den externen Schlüsselbezeichner, den vom Proxy zurückgegebenen HTTP-Statuscode und die Round-Trip-Latenz. Die vollständige Anleitung zur Protokollierung und Überwachung, einschließlich Warnungskonfiguration und proxyseitiger Protokollkorrelation, finden Sie unter Protokollierung und Überwachung für die Verwaltung von externen HSM-Schlüsseln.

Bereinigen von Ressourcen

So entfernen Sie die in dieser Schnellstartanleitung erstellten Ressourcen:

  1. Löschen Sie die Referenz des verwalteten HSM-Schlüssels:

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

  2. Löschen Sie die Verbindung zur externen Schlüsselverwaltung:

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

Das Löschen des Verweises auf den Managed HSM-Schlüssel wirkt sich nicht auf das Schlüsselmaterial in Ihrem externen HSM aus. Dieser Schlüssel verbleibt in Ihrem HSM, bis Sie ihn dort entfernen.

Nächste Schritte

  • Last updated on