Specifikation för Bring your own key

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 textform.
• Utanför en HSM skyddas nyckeln som ska överföras alltid av en nyckel som finns i Azure Key Vault HSM

Terminologi

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 HSM-källan ligger i allmänhet utanför omfånget för den här specifikationen. Microsoft förväntar sig att HSM-leverantören ska ta fram dokumentation som medföljer deras BYOK-verktyg för att inkludera sådana konfigurationssteg.

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

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 hjälp av HSM-leverantörens BYOK-verktyg

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älliga. 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 är den privata nyckeln ASN.1 DER-kodning [RFC3447] omsluten 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 nyckelns råa byte

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

• 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 chifferbloben.

Formatet för överföringsbloben använder JSON Web Encryption kompakt serialisering (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 namnet och versionen 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 nyckeltypen och kurvnamnet.

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, resulterar det i att en REST API-begäran skickas 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 kodas i Base64-format.

Referenser

• Utvecklarguide för Key Vault

Nästa steg

• Stegvisa BYOK-instruktioner: Importera HSM-skyddade nycklar till Key Vault (BYOK)