Specifica per BYOK (Bring Your Own Key)

2025-06-19

Questo documento descrive le specifiche per l'importazione di chiavi protette da HSM dagli HSM on-premises dei clienti in Key Vault.

Sceneggiatura

Un cliente di Key Vault vuole trasferire in modo sicuro una chiave dal modulo di protezione hardware locale all'esterno di Azure, nel modulo di protezione hardware che esegue il backup di Azure Key Vault. Il processo di importazione di una chiave generata all'esterno di Key Vault è definito BYOK (Bring Your Own Key).

Di seguito sono riportati i requisiti:

La chiave da trasferire non esiste mai all'esterno di un HSM in formato testo normale.
All'esterno di un modulo di protezione hardware, la chiave da trasferire è sempre protetta da una chiave contenuta nel modulo di protezione hardware di Azure Key Vault

Terminologia

Nome chiave	Tipo di chiave	Origine	Descrizione
Chiave di scambio delle chiavi (KEK)	RSA	HSM di Azure Key Vault	Coppia di chiavi RSA supportata da HSM generata in Azure Key Vault
Tasto di avvolgimento	AES	Modulo di sicurezza hardware del fornitore	Una chiave AES [temporanea] generata da HSM in locale
Chiave di destinazione	RSA, EC, AES (solo HSM gestito)	Modulo di sicurezza hardware del fornitore	La chiave da trasferire al modulo di sicurezza hardware HSM di Azure Key Vault

Chiave di scambio di chiave (KEK): chiave supportata dal modulo di protezione hardware generata dal cliente nell'insieme di credenziali delle chiavi in cui verrà importata la chiave BYOK. Questa chiave di scambio delle chiavi (KEK) deve avere le proprietà seguenti:

Si tratta di una chiave RSA-HSM (a 4096 bit o a 3072 bit o a 2048 bit)
Ha un key_ops fisso (SOLO import), che consente di essere usato SOLO durante BYOK
Deve trovarsi nello stesso insieme di credenziali in cui viene importata la chiave di destinazione

Passaggi utente

Per eseguire un trasferimento di chiavi, un utente segue questa procedura:

Generare KEK.
Recupera la chiave pubblica del KEK.
Usando lo strumento BYOK fornito dal fornitore del modulo di protezione hardware: importare la chiave di scambio delle chiavi (KEK) nel modulo di protezione hardware di destinazione ed esportare la chiave di destinazione protetta dalla chiave di scambio delle chiavi (KEK).
Importare la chiave di destinazione protetta in Azure Key Vault.

I clienti usano lo strumento BYOK e la documentazione forniti dal fornitore del modulo di protezione hardware per completare i passaggi 3. Viene prodotto un BLOB di trasferimento chiavi (un file ".byok").

Vincoli HSM

Il modulo di protezione hardware esistente può applicare vincoli alla chiave gestita, tra cui:

Potrebbe essere necessario configurare l'HSM per consentire l'esportazione basata sul wrap delle chiavi
Potrebbe essere necessario contrassegnare la chiave di destinazione come CKA_EXTRACTABLE affinché l'HSM consenta l'esportazione controllata.
In alcuni casi, la chiave KEK e la chiave di wrapping possono essere contrassegnate come CKA_TRUSTED, il che consente di eseguire il wrapping delle chiavi nel modulo di protezione hardware.

La configurazione del modulo di protezione hardware di origine è, in genere, al di fuori dell'ambito di questa specifica. Microsoft si aspetta che il fornitore dell'HSM produca la documentazione associata al loro strumento BYOK per includere tali passaggi di configurazione.

Annotazioni

Diversi di questi passaggi possono essere eseguiti usando altre interfacce, ad esempio Azure PowerShell e il portale di Azure. Possono anche essere eseguite a livello di codice usando funzioni equivalenti in Key Vault SDK.

Generare KEK

Usare il comando az keyvault key create di per creare la chiave kek con operazioni chiave impostate per l'importazione. Prendere nota dell'identificatore di chiave 'kid' restituito dal comando seguente.

az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --vault-name ContosoKeyVaultHSM

Annotazioni

I servizi supportano lunghezze kek diverse; Azure SQL, ad esempio, supporta solo lunghezze di chiave di 2048 o 3072 byte. Per informazioni specifiche, vedere la documentazione relativa al servizio.

Recupera la chiave pubblica del KEK

Scaricare la parte pubblica della chiave KEK e archiviarla in un file PEM.

az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem

Generare un blob di trasferimento delle chiavi utilizzando lo strumento BYOK fornito dal fornitore dell'HSM

Il cliente usa lo strumento BYOK fornito dal fornitore HSM per creare un BLOB di trasferimento delle chiavi (archiviato come file ".byok"). La chiave pubblica KEK (come file pem) è uno degli input per questo strumento.

BLOB di trasferimento delle chiavi

A lungo termine, Microsoft vuole usare il meccanismo pkCS#11 CKM_RSA_AES_KEY_WRAP per trasferire la chiave di destinazione in Azure Key Vault, poiché questo meccanismo produce un singolo BLOB e, più importante, la chiave AES intermedia viene gestita dai due moduli di protezione hardware ed è garantito che sia temporanea. Questo meccanismo non è attualmente disponibile in alcuni HSM (moduli di sicurezza hardware), ma la combinazione della protezione della chiave di destinazione con CKM_AES_KEY_WRAP_PAD usando una chiave AES e della protezione della chiave AES con CKM_RSA_PKCS_OAEP produce un BLOB equivalente.

Il testo non crittografato della chiave di destinazione dipende dal tipo di chiave:

Per una chiave RSA, la codifica ASN.1 DER della chiave privata [RFC3447] avvolta nel formato PKCS#8 [RFC5208].
Per una chiave EC, la codifica DER ASN.1 della chiave privata [RFC5915] incapsulata in PKCS#8 [RFC5208]
Per una chiave a otto bit, i byte grezzi della chiave

I byte per la chiave di testo non crittografato vengono quindi trasformati usando il meccanismo di CKM_RSA_AES_KEY_WRAP:

Viene generata una chiave AES temporanea e crittografata utilizzando una chiave di wrapping RSA con RSA-OAEP e SHA1.
La chiave di testo semplice codificata viene crittografata utilizzando la chiave AES tramite il wrapping della chiave AES con padding.
La chiave AES crittografata e la chiave crittografata di testo non crittografato vengono concatenate per produrre il BLOB di testo crittografato finale.

Il formato del blob di trasferimento utilizza principalmente la serializzazione compatta di JSON Web Encryption (RFC7516) come veicolo per trasmettere i metadati richiesti al servizio per una corretta decrittazione.

Se si usa CKM_RSA_AES_KEY_WRAP_PAD, la serializzazione JSON del BLOB di trasferimento sarà:

{
  "schema_version": "1.0.0",
  "header":
  {
    "kid": "<key identifier of the KEK>",
    "alg": "dir",
    "enc": "CKM_RSA_AES_KEY_WRAP"
  },
  "ciphertext":"BASE64URL(<ciphertext contents>)",
  "generator": "BYOK tool name and version; source HSM name and firmware version"
}

kid = identificatore chiave del KEK. Per le chiavi di Key Vault, l'aspetto è simile al seguente: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
alg = algoritmo.
dir = Modalità diretta, ovvero il bambino a cui si fa riferimento viene usato per proteggere direttamente il testo crittografato che rappresenta una rappresentazione accurata di CKM_RSA_AES_KEY_WRAP
generator: campo informativo che indica il nome e la versione dello strumento BYOK e il produttore e il modello del modulo di protezione hardware di origine. Queste informazioni sono destinate all'uso nella risoluzione dei problemi e nel supporto.

Il BLOB JSON viene archiviato in un file con estensione ".byok", in modo che il client di Azure PowerShell o dell'interfaccia della riga di comando lo consideri correttamente quando vengono usati i comandi 'Add-AzKeyVaultKey' (PSH) o 'az keyvault key import' (CLI).

Caricare il BLOB di trasferimento della chiave per importare la chiave del modulo di protezione hardware

I clienti trasferiscono il file BLOB di trasferimento chiavi ("byok") in una workstation online e quindi eseguono un comando az keyvault key import per importare questo BLOB come nuova chiave supportata dal modulo di protezione hardware in Key Vault.

Per importare una chiave RSA, usare questo comando:

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok --ops encrypt decrypt

Per importare una chiave EC, è necessario specificare il tipo di chiave e il nome della curva.

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file --kty EC-HSM --curve-name "P-256" KeyTransferPackage-ContosoFirstHSMkey.byok --ops sign verify

Quando questo comando viene eseguito, viene inviato una richiesta API REST come indicato di seguito:

PUT https://contosokeyvaulthsm.vault.azure.net/keys/ContosoFirstHSMKey?api-version=7.0

Corpo della richiesta durante l'importazione di una chiave RSA:

{
  "key": {
    "kty": "RSA-HSM",
    "key_ops": [
      "decrypt",
      "encrypt"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

Corpo della richiesta durante l'importazione di una chiave EC:

{
  "key": {
    "kty": "EC-HSM",
    "crv": "P-256",
    "key_ops": [
      "sign",
      "verify"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

Il valore "key_hsm" è l'intero contenuto di KeyTransferPackage-ContosoFirstHSMkey.byok codificato nel formato Base64.

Riferimenti

Guida allo sviluppatore per Key Vault

Passaggi successivi

Istruzioni dettagliate per la crittografia BYOK: Importare chiavi protette da HSM in Key Vault (BYOK)