Snabbstart: Skapa din första externa nyckel med hjälp av Azure CLI

I den här snabbstarten ansluter du din externa HSM till Managed HSM, skapar en extern nyckelreferens och testar sökvägen för nyckelskydd. Sedan använder du URI:n för Managed HSM-nyckel för att konfigurera cmk-kryptering (customer-managed-key) i vila i en kompatibel Azure tjänst.

Information om krypteringsmodellen och tjänstkompatibiliteten finns i Vad är extern nyckelhantering för Managed HSM?

Om du föredrar att använda Azure-portalen kan du läsa Snabbstart: Skapa din första externa nyckel med hjälp av Azure portalen.

Prerequisites

Innan du börjar behöver du:

En befintlig hanterad HSM som är distribuerad i valfri offentlig Azure-region, i en prenumeration som är aktiverad för hantering av externa nycklar. Information om hur du skapar en hanterad HSM finns i Snabbstart: Etablera och aktivera en hanterad HSM med hjälp av Azure CLI.
En fungerande EKM-proxy kan nås från Azure. Proxyn måste implementera API-specifikationen för EKM-proxy. För leverantörer som stöds, se Vad är hanterad HSM extern nyckelhantering?.
En nyckel som skapats i din externa HSM med en känd extern nyckelidentifierare. Den externa nyckelidentifieraren är den identifierare som proxyn använder för att leta upp nyckeln.
Rot-CA-certifikatet (PEM-format) som har signerat din proxys TLS-servercertifikat.
Azure CLI version 2.x med det senaste keyvault tillägget installerat. Kör az extension add --name keyvault eller az extension update --name keyvault hämta den senaste versionen.
Rollen Managed HSM EKM Administrator för att hantera externa nyckelhanteringsanslutningar och Managed HSM Crypto User rollen för att skapa och använda nycklar. Information om rolltilldelningssteg finns i Hanterad HSM-åtkomstkontroll.

az login

Ange din prenumeration om du har fler än en:

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

Visa det hanterade HSM-klientcertifikatet

Hanterad HSM uppvisar ett X.509-klientcertifikat för din EKM-proxy vid varje inkommande anslutning med ömsesidig TLS (mTLS). Innan du skapar den externa nyckelhanteringsanslutningen, hämtar du certifikatets Common Name (CN) och rot-CA-certifikatet och lägger till det i proxyns tillåtslista. Detta gör att proxyn kan verifiera att anslutningen kommer från din hanterade HSM, inte en godtycklig anropare.

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

Utdata ser ut ungefär så här:

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

Konfigurera proxyn för att lita på anslutningar som presenterar certifikat med subjectCommonName och rotade till ett av certifikaten i caCertificates listan ovan. De exakta stegen beror på proxyleverantören.

Note

Information om rotationssteg och certifikatlivscykel finns i Konfigurera nätverk och mTLS för hantering av hanterade HSM-externa nycklar.

Skapa den externa nyckelhanteringsanslutningen

Den externa nyckelhanteringsanslutningen binder din hanterade HSM till en enda EKM-proxy. Den innehåller proxyadressen, server-CA:ns förtroendeankare och ett valfritt sökvägsprefix.

Det här avsnittet skapar en offentlig internetanslutning. För Private Link följer du i stället Konfigurera Azure Private Link-modellen (förhandsversion) och fortsätt sedan med Verifiera anslutningen.

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

Parameterreferens:

--hsm-name: Namnet på ditt hanterade HSM.
--host: Det fullständigt kvalificerade värdnamnet för din EKM-proxy. Till exempel proxy.contoso.com. Proxyn måste lyssna på TCP-port 443. En port som inte är standard stöds inte.
--server-ca-certificate: Anger sökvägen till rot-CA-certifikatfilen (PEM- eller DER-format) som används för att verifiera proxyns TLS-servercertifikat.
--path-prefix (valfritt): Ett URL-sökvägsprefix om din proxy multiplexar flera kunder eller pooler efter sökväg. Till exempel /contoso/prod.

Note

Överför rot-CA-certifikatet till --server-ca-certificate, inte proxyns slutentitetscertifikat. Hanterad HSM använder den här certifikatutfärdaren för att validera hela certifikatkedjan som din proxy presenterar under mTLS-handskakningen. Om du skickar lövcertifikatet i stället misslyckas handskakningen för eventuell certifikatförnyelse.

Kontrollera anslutningen

När du har skapat anslutningen kontrollerar du att Managed HSM kan nå proxyn:

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

Det här kommandot anropar proxyns /info slutpunkt via den konfigurerade anslutningen. Ett lyckat resultat ser ungefär ut så här:

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

Vanliga felorsaker är brandväggsregler som blockerar proxyporten, ett felaktigt --host värde eller proxyn som avvisar det hanterade HSM-klientcertifikatet. Information om åtgärdssteg finns i Felsöka extern nyckelhantering för Managed HSM.

Skapa den externa nyckeln

Skapa en hanterad HSM-nyckelreferens som pekar på den externa nyckeln i din HSM. Hanterad HSM genererar inget nyckelmaterial. Det här kommandot registrerar en referens till en befintlig nyckel som identifieras av dess externa nyckelidentifierare.

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

Parameterreferens:

--external-key-id: Den externa nyckelidentifieraren som är registrerad på proxyn. Det här är den identifierare som proxyn använder för att leta upp rätt nyckel i din externa HSM.
--hsm-name: Namnet på ditt hanterade HSM.
--name: Det namn du vill ge nyckelreferensen för Managed HSM. Detta blir en del av den nyckel-URI som Azure tjänster använder.

Important

Den externa nyckelidentifieraren är oföränderlig under en nyckelversions livslängd. Du kan inte ändra den när du har skapat den. För att rotera nyckeln skapar du en ny nyckelversion med en ny extern nyckelidentifierare med hjälp av az keyvault key create med samma --name. Nyckel-URI :n (HSM URI + nyckelnamn) förblir stabil mellan olika versioner. endast versionssegmentet ändras.

Kommandot returnerar nyckel-URI:n i formuläret https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Behåll den här URI:n för att konfigurera din Azure-tjänst.

Verifiera radbrytning/ingen radbrytning

Testa nyckelskyddssökvägen med wrapping och unwrapping i en tur-och-retur-process. Den externa HSM:n utför åtgärderna via proxyn och Managed HSM returnerar resultatet. Det här testet bekräftar att key path fungerar. Den konfigurerar eller verifierar inte en Azure tjänsts CMK-integrering.

Note

Använd dataplanslutpunkterna wrapkey och unwrapkey med az rest för det här testet. az keyvault key encrypt anropar en annan nyckel-API-åtgärd och ersätter inte wrapning av en datakrypteringsnyckel.

Skapa en begärandetext för wrap-åtgärden. Ange value till det base64url-kodade nyckelmaterial som du vill omsluta.
```
{
  "alg": "RSA-OAEP-256",
  "value": "<base64url-encoded-plaintext-key>"
}
```
Spara den som wrapkey.json. För externa AES-nycklar använder du "alg": "A256KW" i stället för RSA-OAEP-256.

wrapkey Anropa slutpunkten på din nyckelreferens:

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

Svaret returnerar nyckelversionen (kid) och ett value fält som innehåller den base64url-kodade omslutna nyckeln. Kopiera value för nästa steg.

Skapa en begärandetext för unwrap-åtgärden med det wrappade value från föregående steg:
```
{
  "alg": "RSA-OAEP-256",
  "value": "<wrapped-value-from-previous-step>"
}
```
Spara den som unwrapkey.json.
unwrapkey Anropa slutpunkten för att bekräfta att tur och retur är korrekt:
```
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
```
Ett lyckat svar returnerar den ursprungliga klartexten value som du omslutit i det första steget. Om uppackningen misslyckas kan du läsa Felsöka extern nyckelhantering för Managed HSM för information om proxyfelkoder och åtgärdssteg.

Använd nyckeln med en Azure-tjänst

Slutför arbetsbelastningsintegreringen genom att följa cmk-konfigurationsdokumentationen för din Azure-tjänst:

Bekräfta att tjänsten stöder CMK:er med Hanterad HSM och att den externa nyckelns typ och algoritm uppfyller kraven.
Ge den identitet som används av tjänsten de nödvändiga lokala RBAC-behörigheterna för Managed HSM. Vägledning för rolltilldelning finns i åtkomstkontroll för Managed HSM.
Konfigurera tjänstens CMK-inställningar med din hanterade HSM-nyckel-URI. Använd det versionshanterade eller oversionerade URI-format som krävs av den tjänsten. För Azure Storage, se Konfigurera kundhanterade nycklar med Azure Key Vault Hanterad HSM.
Bekräfta att tjänsten rapporterar den förväntade CMK-konfigurationen och utför sedan en läs-/skrivåtgärd på den skyddade arbetsbelastningen. Granska tjänstens diagnostik och Managed HSM external key management-loggar om åtgärden misslyckas.

Tjänsten Azure använder sin befintliga Managed HSM-integrering. Den behöver inte din externa HSM:s leverantörsspecifika API eller autentiseringsuppgifter.

Visa granskningsloggar

Varje EKM-proxyanrop skapar en EkmProxyOperation post i dina hanterade HSM-diagnostikloggar. Så här frågar du efter dem i Log Analytics:

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

Loggen innehåller åtgärdstypen (wrap eller unwrap), den externa nyckelidentifieraren, HTTP-statuskoden som returneras av proxyn och svarstiden tur och retur. Den fullständiga loggnings- och övervakningsguiden, inklusive aviseringskonfiguration och loggkorrelation på proxysidan, finns i Loggning och övervakning för hantering av hanterade HSM-externa nycklar.

Rensa resurser

Om du har konfigurerat en Azure-tjänst för att använda den här nyckeln, migrera arbetsbelastningen till en annan nyckel innan du tar bort referensen eller anslutningen. Behåll den externa nyckeln och dess anslutning så länge arbetsbelastningens data, säkerhetskopior eller ögonblicksbilder kräver det.

Så här tar du bort resurserna som skapades i den här snabbstarten:

Ta bort den hanterade HSM-nyckelreferensen:

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

Ta bort den externa nyckelhanteringsanslutningen:

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

Om du tar bort referensen för hanterad HSM-nyckel påverkas inte nyckelmaterialet i din externa HSM. Den nyckeln finns kvar i din HSM tills du tar bort den där.

Nästa steg

Snabbstart: Skapa din första externa nyckel med hjälp av Azure-portalen: slutför samma flöde i Azure portalen.
Extern nyckellivscykel i Managed HSM extern nyckelhantering: nyckelrotation, versionshantering och inaktivering av externa nycklar.
Konfigurera nätverk och mTLS för extern nyckelhantering för Managed HSM: offentlig Internetanslutning, Private Link integrering (förhandsversion) och certifikatrotation.
Loggning och övervakning för hanterad HSM-hantering av externa nycklar: aviseringsregler, KQL-frågor (Kusto Query Language) och proxyloggkorrelation.
Felsöka extern nyckelhantering för Managed HSM: felkoder, proxydiagnostik och åtgärdssteg.

Feedback

Var den här sidan till hjälp?

Uppdaterades senast 2026-10-16

Snabbstart: Skapa din första externa nyckel med hjälp av Azure CLI

Prerequisites

Logga in på Azure

Visa det hanterade HSM-klientcertifikatet

Skapa den externa nyckelhanteringsanslutningen

Kontrollera anslutningen

Skapa den externa nyckeln

Verifiera radbrytning/ingen radbrytning

Använd nyckeln med en Azure-tjänst

Visa granskningsloggar

Rensa resurser

Nästa steg

Feedback

Ytterligare resurser