Quickstart: Uw eerste externe sleutel maken met behulp van de Azure CLI (preview)

Important

Beheer van externe sleutels voor Managed HSM is beschikbaar als preview. Preview-functies worden aan u beschikbaar gesteld op voorwaarde dat u akkoord gaat met de aanvullende gebruiksvoorwaarden. Sommige aspecten van deze functie kunnen veranderen voordat deze algemeen beschikbaar is.

In deze quickstart registreert u een EKM-proxyverbinding met uw beheerde HSM en maakt u vervolgens een beheerde HSM-sleutelverwijzing die verwijst naar een sleutel in uw door de klant beheerde HSM. Aan het einde voert u een wrap/unwrap-heen-en-weerronde uit om te controleren of de integratie werkt.

Als u liever de Azure-portal gebruikt, raadpleegt u quickstart: Uw eerste externe sleutel maken met behulp van de Azure-portal.

Prerequisites

Voordat u begint, hebt u het volgende nodig:

  • Een bestaande beheerde HSM die is geïmplementeerd in een openbare Azure-regio, waarbij extern sleutelbeheer is ingeschakeld voor het abonnement door uw Microsoft-accountteam. Neem contact op met uw accountteam om inschakeling aan te vragen. Zie quickstart: Een beheerde HSM inrichten en activeren met behulp van Azure CLI om een beheerde HSM te maken.
  • Een operationele EKM-proxy bereikbaar vanaf Azure. De proxy moet de EKM Proxy API-specificatie implementeren. Zie Wat is extern sleutelbeheer voor beheerde HSM's? voor ondersteunde leveranciers.
  • Een in uw externe HSM gemaakte sleutel met een bekende externe sleutel-ID. De externe-sleutel-id is de id die uw proxy gebruikt om de sleutel op te zoeken.
  • Het root-CA-certificaat (PEM-formaat) waarmee het TLS-servercertificaat van uw proxy is ondertekend.
  • Azure CLI versie 2.x waarop de nieuwste keyvault extensie is geïnstalleerd. Voer az extension add --name keyvault of az extension update --name keyvault uit om de nieuwste versie te krijgen.
  • De Managed HSM EKM Administrator rol voor het beheren van externe sleutelbeheerverbindingen en de rol voor het Managed HSM Crypto User maken en gebruiken van sleutels. Zie Toegangsbeheer voor beheerde HSM's voor stappen voor roltoewijzing.

Aanmelden bij Azure

az login

Stel uw abonnement in als u meer dan één abonnement hebt:

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

Het beheerde HSM-clientcertificaat weergeven

Managed HSM biedt bij elke inkomende mutual TLS-verbinding (mTLS) een X.509-clientcertificaat aan uw EKM-proxy aan. Voordat u de verbinding met extern sleutelbeheer maakt, haalt u de common name van het certificaatsubject en het root-CA-certificaat op en voegt u deze toe aan de allowlist van uw proxy. Dit is hoe de proxy valideert dat de verbinding afkomstig is van uw beheerde HSM, niet een willekeurige beller.

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

De uitvoer ziet er ongeveer als volgt uit:

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

Configureer uw proxy om verbindingen te vertrouwen die een certificaat met het subjectCommonName certificaat presenteren en die zijn geroot naar een van de certificaten in caCertificates de bovenstaande lijst. De exacte stappen zijn afhankelijk van uw proxyleverancier.

Note

Zie Netwerken en mTLS configureren voor extern sleutelbeheer voor Managed HSM voor rotatiestappen en details over de levenscyclus van certificaten.

De verbinding voor extern sleutelbeheer maken

De externe-sleutelbeheerverbinding verbindt uw beheerde HSM met één EKM-proxy. Het bevat het proxyadres, het vertrouwensanker voor de server-CA en een optioneel padvoorvoegsel.

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

Parameterreferentie:

  • --hsm-name: De naam van uw beheerde HSM.
  • --host: De volledig gekwalificeerde hostnaam van uw EKM-proxy. Bijvoorbeeld: proxy.contoso.com. De proxy moet luisteren op TCP-poort 443; een niet-standaardpoort wordt niet ondersteund in de preview-versie.
  • --server-ca-certificate: Hiermee geeft u het pad naar het basis-CA-certificaatbestand (PEM- of DER-indeling) op dat wordt gebruikt om het TLS-servercertificaat van de proxy te verifiëren.
  • --path-prefix (optioneel): een URL-padvoorvoegsel als uw proxy meerdere klanten of pools via het pad multiplexeert. Bijvoorbeeld: /contoso/prod.

Note

Geef het basis-CA-certificaat door aan --server-ca-certificate, niet aan het basiscertificaat van de proxy. Beheerde HSM gebruikt deze CA om de volledige certificaatketen te valideren die door uw proxy wordt gepresenteerd tijdens de mTLS-handshake. Als in plaats daarvan het eindentiteitscertificaat wordt doorgegeven, mislukt de handshake bij elke certificaatvernieuwing.

De verbinding verifiëren

Nadat u de verbinding hebt gemaakt, controleert u of de beheerde HSM uw proxy kan bereiken:

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

Met deze opdracht wordt het eindpunt van /info de proxy aangeroepen via de geconfigureerde verbinding. Geslaagde uitvoer ziet er ongeveer als volgt uit:

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

Veelvoorkomende foutoorzaken zijn firewallregels die de proxypoort blokkeren, een onjuiste --host waarde of de proxy die het beheerde HSM-clientcertificaat weigert. Zie Problemen met extern sleutelbeheer van beheerde HSM oplossen voor herstelstappen.

De externe sleutel maken

Maak een verwijzing naar een beheerde HSM-sleutel die verwijst naar de externe sleutel in uw HSM. Er wordt geen sleutelmateriaal gegenereerd binnen beheerde HSM. Met deze opdracht wordt een verwijzing geregistreerd naar een bestaande sleutel die is geïdentificeerd door de externe sleutel-id.

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

Parameterreferentie:

  • --external-key-id: de externe-sleutel-id die is geregistreerd bij uw proxy. Dit is de id die de proxy gebruikt om de juiste sleutel in uw externe HSM op te zoeken.
  • --hsm-name: De naam van uw beheerde HSM.
  • --name: De naam die u de beheerde HSM-sleutelreferentie wilt geven. Dit wordt onderdeel van de sleutel-URI die Azure services gebruiken.

Important

De externe-sleutel-id is onveranderbaar voor de levensduur van een sleutelversie. U kunt deze niet wijzigen na het maken. Als u de sleutel wilt rouleren, maakt u een nieuwe sleutelversie met een nieuwe externe sleutel-id met behulp van az keyvault key create met dezelfde --name. De sleutel-URI (HSM URI + sleutelnaam) blijft stabiel in verschillende versies; alleen het versiesegment wordt gewijzigd.

De opdracht retourneert de sleutel-URI in het formulier https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Gebruik deze URI bij het configureren van door de klant beheerde sleutelinstellingen (CMK) in Azure services.

Inpakken/uitpakken controleren

Controleer de integratie van begin tot eind met een wrap/unwrap-cyclus. De werkelijke inpak- en uitpakbewerkingen vinden plaats op uw proxy en externe HSM — Managed HSM routeert de aanvraag en retourneert het resultaat.

Important

Gebruik dit niet az keyvault key encrypt om een externe sleutel te testen. Met deze opdracht wordt een encrypt bewerking uitgevoerd, die extern sleutelbeheer niet ondersteunt: extern sleutelbeheer dient wrapKey en unwrapKey alleen. Roep in plaats daarvan de wrapkey- en unwrapkey-data-plane-eindpunten rechtstreeks aan met az rest.

  1. Maak een aanvraagtekst voor de wrap-bewerking. Stel value in op het met base64url gecodeerde sleutelmateriaal dat u wilt verpakken.

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

    Sla het op als wrapkey.json. Gebruik voor externe AES-sleutels "alg": "A256KW" in plaats van RSA-OAEP-256.

  2. Roep het wrapkey eindpunt aan op uw sleutelreferentie:

    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

    Het antwoord retourneert de sleutelversie (kid) en een value veld met de met base64url gecodeerde verpakte sleutel. Kopieer de value voor de volgende stap.

  3. Maak een aanvraagtekst voor de unwrap-bewerking, met de verpakte value uit de vorige stap:

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

    Sla het op als unwrapkey.json.

  4. Roep het eindpunt aan om de juistheid van de unwrapkey retour te bevestigen:

    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

    Een geslaagd antwoord retourneert de oorspronkelijke tekst zonder opmaak value die u in de eerste stap hebt verpakt. Als het uitpakken mislukt, raadpleegt u Probleemoplossing voor extern HSM-sleutelbeheer voor proxyfoutcodes en herstelstappen.

Auditlogboeken weergeven

Elke EKM-proxyaanroep produceert een EkmProxyOperation vermelding in de diagnostische logboeken van beheerde HSM. Ga als volgt te werk om een query uit te voeren in Log Analytics:

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

Het logboek bevat het bewerkingstype (wrap of unwrap), de externe-sleutel-id, de HTTP-statuscode die door de proxy wordt geretourneerd en de retourlatentie. Zie Logregistratie en monitoring voor beheer van externe sleutels voor Managed HSM voor de volledige handleiding voor logregistratie en monitoring, inclusief waarschuwingsconfiguratie en logcorrelatie aan de proxyzijde.

De hulpbronnen opschonen

De resources verwijderen die in deze quickstart zijn gemaakt:

  1. Verwijder de verwijzing naar de beheerde HSM-sleutel:

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

  2. Verwijder de externe-sleutelbeheerverbinding:

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

Het verwijderen van de referentie voor beheerde HSM-sleutels heeft geen invloed op het sleutelmateriaal in uw externe HSM. Deze sleutel blijft in uw HSM staan totdat u deze daar verwijdert.

Volgende stappen 

  • Last updated on