Guida introduttiva: Creare la prima chiave esterna usando il interfaccia della riga di comando di Azure (anteprima)

Importante

La gestione esterna delle chiavi di Managed HSM è in anteprima. Le funzionalità di anteprima vengono rese disponibili all'utente in base alla condizione che si accettano le condizioni supplementari per l'utilizzo. Alcuni aspetti di questa funzionalità potrebbero cambiare prima della disponibilità generale.

In questo avvio rapido si registra una connessione al proxy EKM per il proprio HSM gestito, quindi si crea un riferimento a una chiave di HSM gestito che punta a una chiave nell'HSM gestito dal cliente. Al termine, si esegue un ciclo completo di wrapping/unwrapping per verificare che l'integrazione funzioni.

Se si preferisce usare il portale di Azure, vedere Avvio rapido: Creare la prima chiave esterna usando il portale di Azure.

Prerequisiti

Prima di iniziare, è necessario disporre di quanto segue:

  • Un HSM gestito esistente distribuito in qualsiasi area pubblica di Azure, con la gestione esterna delle chiavi abilitata per la sottoscrizione dal team Microsoft responsabile dell'account. Contatta il team responsabile dell'account per richiedere l'abilitazione. Per creare un modulo di protezione hardware gestito, vedere Avvio rapido: Effettuare il provisioning e attivare un modulo di protezione hardware gestito usando interfaccia della riga di comando di Azure.
  • Un proxy EKM operativo raggiungibile da Azure. Il proxy deve implementare la specifica dell'API proxy EKM. Per i fornitori supportati, vedere Che cos'è la gestione delle chiavi esterne del modulo di protezione hardware gestito?.
  • Chiave creata nell'HSM esterno con un identificatore esterno della chiave noto. L'identificatore di chiave esterna è l'identificatore usato dal proxy per cercare la chiave.
  • Il certificato radice della CA, in formato PEM, che ha firmato il certificato TLS del server proxy.
  • interfaccia della riga di comando di Azure versione 2.x con l'estensione più recente keyvault installata. Eseguire az extension add --name keyvault o az extension update --name keyvault per ottenere la versione più recente.
  • Ruolo Managed HSM EKM Administrator per gestire le connessioni di gestione delle chiavi esterne e il Managed HSM Crypto User ruolo per creare e usare le chiavi. Per i passaggi per l'assegnazione dei ruoli, vedi Controllo di accesso per HSM gestito.

Accedere ad Azure

az login

Impostare la sottoscrizione se sono presenti più di una:

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

Mostrare il certificato client di Managed HSM

Managed HSM presenta un certificato client X.509 al tuo proxy EKM per ogni connessione mutual TLS (mTLS) in ingresso. Prima di creare la connessione alla gestione esterna delle chiavi, recuperare il nome comune del soggetto del certificato e il certificato della CA radice e aggiungerli all'elenco consentito del proxy. Questo è il modo in cui il proxy convalida che la connessione proviene dal modulo di protezione hardware gestito, non da un chiamante arbitrario.

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

L'output è simile al seguente:

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

Configurare il proxy in modo che consideri attendibili le connessioni che presentano certificati con subjectCommonName e che sono ancorati a uno dei certificati nell'elenco caCertificates sopra. I passaggi esatti dipendono dal fornitore del proxy.

Note

Per informazioni dettagliate sui passaggi di rotazione e sul ciclo di vita dei certificati, vedere Configurare la rete e mTLS per la gestione delle chiavi esterne del modulo di protezione hardware gestito.

Creare la connessione esterna per la gestione delle chiavi

La connessione di gestione delle chiavi esterne associa il tuo Managed HSM a un singolo Proxy EKM. Contiene l'indirizzo del proxy, l'ancora di attendibilità della CA del server e un prefisso del percorso facoltativo.

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

Riferimento ai parametri:

  • --hsm-name: Il nome del tuo Managed HSM.
  • --host: Il nome host completo del tuo proxy EKM. Ad esempio: proxy.contoso.com. Il proxy deve essere in ascolto sulla porta TCP 443; Una porta non standard non è supportata in anteprima.
  • --server-ca-certificate: specifica il percorso del file di certificato CA radice (formato PEM o DER) usato per verificare il certificato del server TLS del proxy.
  • --path-prefix (facoltativo): un prefisso del percorso URL se il proxy instrada più clienti o pool in base al percorso. Ad esempio: /contoso/prod.

Note

Passare il certificato della CA radice a --server-ca-certificate, non il certificato finale del proxy. Il modulo di protezione hardware gestito usa questa CA per convalidare l'intera catena di certificati presentata dal proxy durante l'handshake mTLS. Il passaggio del certificato finale provoca invece il fallimento dell'handshake a ogni rinnovo del certificato.

Verificare la connessione

Dopo aver creato la connessione, verifica che Managed HSM possa raggiungere il proxy:

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

Questo comando chiama l'endpoint del /info proxy tramite la connessione configurata. L'output riuscito è simile al seguente:

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

Le cause di errore comuni includono regole del firewall che bloccano la porta proxy, un valore non corretto --host o il proxy che rifiuta il certificato client del modulo di protezione hardware gestito. Per i passaggi di correzione, vedere Risolvere i problemi di gestione delle chiavi esterne del modulo di protezione hardware gestito.

Creare la chiave esterna

Creare un riferimento a una chiave HSM gestito che punta alla chiave esterna nell'HSM. Nessun materiale chiave viene generato in Managed HSM: questo comando registra un riferimento a una chiave esistente identificata tramite il relativo identificatore di chiave esterna.

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

Riferimento ai parametri:

  • --external-key-id: identificatore di chiave esterna registrato nel proxy. Si tratta dell'identificatore usato dal proxy per cercare la chiave corretta nel modulo di protezione hardware esterno.
  • --hsm-name: Il nome del tuo Managed HSM.
  • --name: Il nome che si desidera assegnare al riferimento della chiave Managed HSM. Questo diventa parte dell'URI della chiave utilizzato dai servizi Azure.

Importante

L'identificatore di chiave esterna non è modificabile per la durata di una versione della chiave. Non è possibile modificarlo dopo la creazione. Per ruotare la chiave, creare una nuova versione della chiave con un nuovo identificatore di chiave esterna usando az keyvault key create con lo stesso --name. L'URI della chiave (URI HSM + nome chiave) rimane stabile tra le versioni; cambia solo il segmento di versione.

Il comando restituisce l'URI della chiave nel formato https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Usare questo URI quando si configurano le impostazioni della chiave gestita dal cliente nei servizi di Azure.

Verificare il wrapping/unwrapping

Confermare l'integrazione end-to-end con un round-trip di wrapping/unwrapping. Le operazioni effettive di wrapping e unwrapping avvengono nel proxy e nell'HSM esterno; HSM gestito instrada la richiesta e restituisce il risultato.

Importante

Non usare az keyvault key encrypt per testare una chiave esterna. Questo comando genera un'operazione encrypt , che la gestione delle chiavi esterne non supporta, ovvero la gestione delle chiavi esterne serve wrapKey e unwrapKey solo. Chiama direttamente con az rest gli endpoint del piano dati wrapkey e unwrapkey invece.

  1. Crea il corpo della richiesta per l'operazione di incapsulamento. Impostare value sul materiale della chiave codificato in base64url di cui si desidera eseguire il wrapping.

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

    Salvarlo come wrapkey.json. Per le chiavi esterne AES, usare "alg": "A256KW" invece di RSA-OAEP-256.

  2. Chiamare l'endpoint nel riferimento della chiave wrapkey:

    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

    La risposta restituisce la versione della chiave (kid) e un campo value contenente la chiave incapsulata con codifica Base64url. Copia il value per il passaggio successivo.

  3. Creare il corpo della richiesta per l'operazione di unwrap, usando il valore sottoposto a wrapping value dal passaggio precedente:

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

    Salvarlo come unwrapkey.json.

  4. Chiamare l'endpoint unwrapkey per confermare la correttezza del percorso di andata e ritorno:

    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

    Una risposta con esito positivo restituisce il testo in chiaro originale value che hai racchiuso nel primo passaggio. Se l’operazione di unwrap non riesce, consulta Risolvere i problemi della gestione delle chiavi esterne di Managed HSM per i codici di errore del proxy e i passaggi per la risoluzione.

Visualizzare i log di controllo

Ogni chiamata al proxy EKM produce una voce EkmProxyOperation nei registri di diagnostica di HSM gestito. Per interrogare questi elementi in Log Analytics:

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

Il log include il tipo di operazione (wrap o unwrap), l'identificatore della chiave esterna, il codice di stato HTTP restituito dal proxy e la latenza di andata e ritorno. Per la guida completa alla registrazione e al monitoraggio, inclusa la configurazione degli avvisi e la correlazione dei log lato proxy, vedere Registrazione e monitoraggio per la gestione delle chiavi esterne del modulo di protezione hardware gestito.

Pulire le risorse

Per rimuovere le risorse create in questa guida introduttiva:

  1. Eliminare il riferimento alla chiave Managed HSM:

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

  2. Eliminare la connessione di gestione delle chiavi esterne:

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

L'eliminazione del riferimento alla chiave in Managed HSM non influisce sul materiale crittografico della chiave nell'HSM esterno. Quella chiave rimane nel tuo HSM finché non la rimuovi da lì.

Passaggi successivi

  • Last updated on