Specifica di BYOK (Bring Your Own Key)

Questo documento descrive le specifiche per l'importazione di chiavi con protezione HSM dai moduli di protezione hardware locali dei clienti in Key Vault.

Scenario

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 supporta 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 modulo di protezione hardware 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 chiave	Origine	Descrizione
Chiave KEK (Key Exchange Key)	RSA	Modulo di protezione hardware di Azure Key Vault	Coppia di chiavi RSA supportata da modulo di protezione hardware generata in Azure Key Vault
Chiave di wrapping	AES	Modulo di protezione hardware del fornitore	Una chiave AES [temporanea] generata dal modulo di protezione hardware in locale
Chiave di destinazione	RSA, EC, AES (solo HSM gestito)	Modulo di protezione hardware del fornitore	Chiave da trasferire nel modulo di protezione hardware di Azure Key Vault

Chiave di scambio delle chiavi (KEK): una 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)
• Avrà un valore key_ops fisso (SOLO ‘import’), che ne consentirà l'uso SOLO durante BYOK
• Deve trovarsi nello stesso insieme di credenziali in cui verrà importata la chiave di destinazione

Passaggi utente

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

1. Generare la chiave di scambio delle chiavi (KEK).
2. Recuperare la chiave pubblica della chiave di scambio delle chiavi (KEK).
3. 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).
4. 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 il Passaggio 3. Viene prodotto un BLOB di trasferimento chiavi (un file con estensione "byok").

Vincoli del modulo di protezione hardware

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

• Potrebbe essere necessario configurare il modulo di protezione hardware per consentire l'esportazione basata sul wrapping delle chiavi
• Potrebbe essere necessario contrassegnare la chiave di destinazione come CKA_EXTRACTABLE per consentire l'esportazione controllata
• In alcuni casi potrebbe essere necessario contrassegnare la chiave di scambio delle chiavi (KEK) e la chiave di wrapping come CKA_TRUSTED, in modo da consentirne l'uso per eseguire il wrapping delle chiavi nel modulo di protezione hardware.

La configurazione del modulo di protezione hardware di origine non rientra in genere nell'ambito di questa specifica. Microsoft si aspetta che il fornitore del modulo di protezione hardware produca la documentazione associata allo strumento BYOK per includere tali passaggi di configurazione.

Nota

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

Generare la chiave di scambio delle chiavi (KEK)

Usare il comando az keyvault key create per creare una chiave di scambio delle chiavi (KEK) con operazioni della chiave impostate su import. Annotare l'identificatore di chiave 'kid' restituito dal comando seguente.

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

Nota

I servizi supportano lunghezze di chiave di scambio delle chiavi (KEK) diverse. Azure SQL, ad esempio, supporta solo le lunghezze delle chiavi pari a 2048 o 3072 byte. Per informazioni specifiche, vedere la documentazione relativa al servizio.

Recuperare la chiave pubblica della chiave di scambio delle chiavi (KEK)

Scaricare la parte chiave pubblica della chiave di scambio delle chiavi (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 usando lo strumento BYOK fornito dal fornitore del modulo di protezione hardware

Il cliente userà lo strumento BYOK fornito dal fornitore del modulo di protezione hardware per creare un BLOB di trasferimento delle chiavi (archiviato come file con estensione "byok"). La chiave di scambio delle chiavi (KEK) pubblica (come file con estensione pem) sarà 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, soprattutto, la chiave AES intermedia viene gestita dai due moduli di protezione hardware ed è garantito che sia temporanea. Questo meccanismo non è attualmente disponibile in alcuni moduli di protezione hardware, ma la combinazione di protezione della chiave di destinazione con CKM_AES_KEY_WRAP_PAD usando una chiave AES e la 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 DER ASN.1 della chiave privata [RFC3447] sottoposta a wrapping in PKCS#8 [RFC5208]
• Per una chiave EC, la codifica DER ASN.1 della chiave privata [RFC5915] sottoposta a wrapping in PKCS#8 [RFC5208]
• Per una chiave ottetto, i byte non elaborati della chiave

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

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

Il formato del BLOB di trasferimento usa principalmente la serializzazione compatta JSON Web Encryption (RFC7516) come veicolo per distribuire i metadati necessari al servizio per la decrittografia corretta.

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 della chiave di scambio delle chiavi (KEK). Per le chiavi di Key Vault è simile al seguente: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
• alg: algoritmo.
• dir: modalità diretta, ovvero il valore kid a cui si fa riferimento viene usato per proteggere direttamente il testo crittografato che rappresenta accuratamente CKM_RSA_AES_KEY_WRAP
• generator: un 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 i client di Azure PowerShell/interfaccia della riga di comando lo gestiscano correttamente quando vengono usati i comandi ‘Add-AzKeyVaultKey’ (PSH) o ‘az keyvault key import’ (interfaccia della riga di comando).

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

Il cliente trasferirà il BLOB di trasferimento della chiave (file con estensione "byok") in una workstation online e quindi eseguirà 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 viene eseguito il comando precedente, viene inviata 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 per gli sviluppatori all'insieme di credenziali delle chiavi

Passaggi successivi

• Istruzioni dettagliate per BYOK: Importare chiavi con protezione HSM in Key Vault (BYOK)