Specifikation för Bring your own key

  • Artikel

Det här dokumentet beskriver specifikationer för import av HSM-skyddade nycklar från kundernas lokala HSM:er till Key Vault.

Scenario

En Key Vault kund vill på ett säkert sätt överföra en nyckel från sin lokala HSM utanför Azure till den HSM som stöder Azure Key Vault. Processen för att importera en nyckel som genereras utanför Key Vault kallas BYOK (Bring Your Own Key).

Följande är kraven:

  • Nyckeln som ska överföras finns aldrig utanför en HSM i oformaterad text.
  • Utanför en HSM skyddas nyckeln som ska överföras alltid av en nyckel som lagras i Azure Key Vault HSM

Terminologi

Nyckelnamn Nyckeltyp Ursprung Beskrivning
Nyckelutbytesnyckel (KEK) RSA Azure Key Vault HSM Ett HSM-säkerhetskopierat RSA-nyckelpar som genererats i Azure Key Vault
Omslutningsnyckel AES Leverantörs-HSM En [tillfällig] AES-nyckel som genereras av HSM lokalt
Målnyckel RSA, EC, AES (endast hanterad HSM) Leverantörs-HSM Nyckeln som ska överföras till Azure Key Vault HSM

Nyckelutbytesnyckel: En HSM-backad nyckel som kunden genererar i nyckelvalvet där BYOK-nyckeln ska importeras. Denna KEK måste ha följande egenskaper:

  • Det är en RSA-HSM-nyckel (4096-bitars eller 3072-bitars eller 2048-bitars)
  • Den har fasta key_ops (ENDAST "import") som gör att den endast kan användas under BYOK
  • Måste finnas i samma valv där målnyckeln ska importeras

Användarsteg

För att utföra en nyckelöverföring utför en användare följande steg:

  1. Generera KEK.
  2. Hämta den offentliga nyckeln för KEK.
  3. Använda HSM-leverantören som tillhandahålls av BYOK-verktyget – Importera KEK till mål-HSM och exportera målnyckeln som skyddas av KEK.
  4. Importera den skyddade målnyckeln till Azure Key Vault.

Kunder använder BYOK-verktyget och dokumentationen från HSM-leverantören för att slutföra steg 3. Den skapar en nyckelöverföringsblob (en ".byok"-fil).

HSM-begränsningar

Befintlig HSM kan tillämpa begränsningar för nyckel som de hanterar, inklusive:

  • HSM kan behöva konfigureras för att tillåta nyckelomslutningsbaserad export
  • Målnyckeln kan behöva markeras CKA_EXTRACTABLE för att HSM ska tillåta kontrollerad export
  • I vissa fall kan KEK och omslutningsnyckeln behöva markeras som CKA_TRUSTED, vilket gör att den kan användas för att omsluta nycklar i HSM.

Konfigurationen av käll-HSM ligger vanligtvis utanför omfånget för den här specifikationen. Microsoft förväntar sig att HSM-leverantören ska producera dokumentation som medföljer deras BYOK-verktyg för att inkludera sådana konfigurationssteg.

Anteckning

Flera av de här stegen kan utföras med hjälp av andra gränssnitt, till exempel Azure PowerShell och Azure Portal. De kan också utföras programmatiskt med motsvarande funktioner i Key Vault SDK.

Generera KEK

Använd kommandot az keyvault key create för att skapa KEK med nyckelåtgärder som ska importeras. Anteckna nyckelidentifieraren "kid" som returneras från kommandot nedan.

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

Anteckning

Tjänsterna stöder olika KEK-längder. Azure SQL stöder till exempel bara nyckellängder på 2 048 eller 3 072 byte. Mer information finns i dokumentationen för din tjänst.

Hämta den offentliga nyckeln för KEK

Ladda ned den offentliga nyckeldelen av KEK och lagra den i en PEM-fil.

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

Generera nyckelöverföringsblob med HSM-leverantören som tillhandahålls av BYOK-verktyget

Kunden använder HSM-leverantören som tillhandahålls av BYOK-verktyget för att skapa en nyckelöverföringsblob (lagras som en ".byok"-fil). Den offentliga KEK-nyckeln (som en .pem-fil) är en av indata till det här verktyget.

Nyckelöverföringsblob

På lång sikt vill Microsoft använda PKCS#11 CKM_RSA_AES_KEY_WRAP mekanism för att överföra målnyckeln till Azure Key Vault eftersom den här mekanismen skapar en enda blob och, ännu viktigare, den mellanliggande AES-nyckeln hanteras av de två HSM:erna och garanteras vara tillfällig. Den här mekanismen är för närvarande inte tillgänglig i vissa HSM:er, men kombinationen av att skydda målnyckeln med CKM_AES_KEY_WRAP_PAD med hjälp av en AES-nyckel och skydda AES-nyckeln med CKM_RSA_PKCS_OAEP skapar en motsvarande blob.

Målnyckelns klartext beror på nyckeltypen:

  • För en RSA-nyckel omsluts den privata nyckeln ASN.1 DER-kodning [RFC3447] i PKCS#8 [RFC5208]
  • För en EC-nyckel är den privata nyckeln ASN.1 DER-kodning [RFC5915] omsluten i PKCS#8 [RFC5208]
  • För en oktettnyckel är råbyte för nyckeln

Byte för klartextnyckeln omvandlas sedan med hjälp av CKM_RSA_AES_KEY_WRAP mekanism:

  • En tillfällig AES-nyckel genereras och krypteras med omslutande RSA-nyckel med RSA-OAEP med SHA1.
  • Den kodade klartextnyckeln krypteras med hjälp av AES-nyckeln med hjälp av AES-nyckelomslutning med utfyllnad.
  • Den krypterade AES-nyckeln och den krypterade klartextnyckeln sammanfogas för att skapa den slutliga chiffertextbloben.

Formatet för överföringsbloben använder JSON Web Encryption compact serialization (RFC7516) främst som ett verktyg för att leverera nödvändiga metadata till tjänsten för korrekt dekryptering.

Om CKM_RSA_AES_KEY_WRAP_PAD används är JSON-serialiseringen av överföringsbloben:

{
  "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 = nyckelidentifierare för KEK. För Key Vault nycklar ser det ut så här:https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
  • alg = algoritm.
  • dir = Direktläge, d.v.s. den refererade ungen används för att direkt skydda chiffertexten som är en korrekt representation av CKM_RSA_AES_KEY_WRAP
  • generator = ett informationsfält som anger namn och version av BYOK-verktyget och HSM-källans tillverkare och modell. Den här informationen är avsedd för felsökning och support.

JSON-bloben lagras i en fil med ett ".byok"-tillägg så att Azure PowerShell/CLI-klienterna hanterar den korrekt när kommandona Add-AzKeyVaultKey (PSH) eller "az keyvault key import" (CLI) används.

Ladda upp nyckelöverföringsblob för att importera HSM-nyckel

Kunden överför nyckelöverföringsbloben (".byok"-filen) till en onlinearbetsstation och kör sedan kommandot az keyvault key import för att importera den här bloben som en ny HSM-backad nyckel till Key Vault.

Om du vill importera en RSA-nyckel använder du det här kommandot:

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

Om du vill importera en EC-nyckel måste du ange nyckeltyp och kurvnamn.

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

När kommandot ovan körs skickas en REST API-begäran på följande sätt:

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

Begärandetext när du importerar en RSA-nyckel:

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

Begärandetext vid import av en EC-nyckel:

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

Värdet "key_hsm" är hela innehållet i KeyTransferPackage-ContosoFirstHSMkey.byok som är kodat i Base64-format.

Referenser

Nästa steg