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

In questa guida introduttiva si connette il modulo di protezione hardware esterno a Managed HSM, si crea un riferimento a una chiave esterna e si testa il percorso di protezione della chiave. Usare quindi l'URI della chiave di HSM gestito per configurare la crittografia dei dati inattivi con chiave gestita dal cliente (CMK) in un servizio di Azure compatibile.

Per la compatibilità del modello di crittografia e del servizio, vedere Che cos'è la gestione delle chiavi esterne di Managed HSM?

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:

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. Ciò consente al proxy di verificare che la connessione provenga dal tuo Managed HSM, 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.

In questa sezione viene creata una connessione Internet pubblica. Per collegamento privato, seguire invece Configurare il modello di collegamento privato di Azure (anteprima) e quindi continuare con Verificare la connessione.

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.
  • --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. Managed HSM non genera alcun materiale crittografico. Questo comando registra un riferimento a una chiave esistente identificata dal 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>. Mantenere questo URI per la configurazione del servizio di Azure.

Verificare il wrapping/unwrapping

Testare il percorso di protezione della chiave con un ciclo di wrapping e unwrapping. L'HSM esterno esegue le operazioni tramite il proxy e Managed HSM restituisce il risultato. Questo test conferma il funzionamento del key path. Non configura o convalida l'integrazione CMK di un servizio Azure.

Note

Usare gli endpoint wrapkey e unwrapkey del data plane con az rest per questo test. az keyvault key encrypt chiama un'operazione API di chiave diversa e non sostituisce il wrapping di una chiave di crittografia dei dati.

  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.

Usare la chiave con un servizio Azure

Completare l'integrazione del carico di lavoro seguendo la documentazione di configurazione cmk del servizio Azure:

  1. Verificare che il servizio supporti i cmk con HSM gestito e che il tipo e l'algoritmo della chiave esterna soddisfino i requisiti.
  2. Concedi all'identità usata dal servizio le autorizzazioni di controllo degli accessi in base al ruolo locale di Managed HSM necessarie. Per indicazioni sull'assegnazione dei ruoli, vedere Controllo di accesso di HSM gestito.
  3. Configurare le impostazioni CMK del servizio con l'URI della chiave Managed HSM. Usare il formato URI con versione o senza versione richiesto dal servizio. Per Archiviazione di Azure, vedere Configurare chiavi gestite dal cliente con Azure Key Vault Managed HSM.
  4. Verificare che il servizio segnala la configurazione cmk prevista, quindi eseguire un'operazione di lettura/scrittura sul carico di lavoro protetto. Esaminare la diagnostica del servizio e i log di gestione delle chiavi esterne di Managed HSM se l'operazione non riesce.

Il servizio Azure usa l'integrazione esistente con Managed HSM. Non sono necessarie l'API o le credenziali specifiche del fornitore del tuo HSM esterno.

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

Se è stato configurato un servizio Azure per l'uso di questa chiave, eseguire la migrazione del carico di lavoro a un'altra chiave prima di eliminare il riferimento o la connessione. Conservare la chiave esterna e la relativa connessione per tutto il tempo in cui i dati, i backup o gli snapshot del carico di lavoro lo richiedono.

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

  • Ultimo aggiornamento: