BYOK-specificatie (Bring Your Own Key)

In dit document worden specificaties beschreven voor het importeren van met HSM beveiligde sleutels van on-premises HSM's van klanten in Key Vault.

Scenario

Een Key Vault klant een sleutel van hun on-premises HSM buiten Azure veilig wil overdragen naar de HSM die ondersteuning biedt voor Azure Key Vault. Het proces voor het importeren van een sleutel die buiten Key Vault is gegenereerd, wordt Aangeduid als Byok (Bring Your Own Key).

Hier volgen de vereisten:

• De sleutel die moet worden overgedragen, bestaat nooit buiten een HSM in tekst zonder opmaak.
• Buiten een HSM wordt de sleutel die moet worden overgedragen altijd beveiligd door een sleutel in de Azure Key Vault HSM

Terminologie

Sleutelnaam	Sleuteltype	Oorsprong	Beschrijving
Key Exchange Key (KEK)	RSA	Azure Key Vault-HSM	Een RSA-sleutelpaar met HSM-ondersteuning dat is gegenereerd in Azure Key Vault
Wrapping-sleutel	AES	HSM-leverancier	Een [kortstondige] AES-sleutel gegenereerd door on-premises HSM
Doelsleutel	RSA, EC, AES (alleen beheerde HSM)	HSM-leverancier	De sleutel die moet worden overgedragen naar de Azure Key Vault-HSM

Sleuteluitwisselingssleutel: een sleutel met HSM-ondersteuning die de klant genereert in de sleutelkluis waar de BYOK-sleutel wordt geïmporteerd. Deze KEK moet de volgende eigenschappen hebben:

• Het is een RSA-HSM-sleutel (4096-bits of 3072-bits of 2048-bits)
• Er is een vaste key_ops (ALLEEN 'importeren'), waardoor het ALLEEN tijdens BYOK kan worden gebruikt
• Moet zich in dezelfde kluis bevinden als waar de doelsleutel wordt geïmporteerd

Gebruikersstappen

Een gebruiker voert de volgende stappen uit om een sleuteloverdracht uit te voeren:

1. KEK genereren.
2. Haal de openbare sleutel van de KEK op.
3. Byok-hulpprogramma van de HSM-leverancier gebruiken: importeer de KEK in de doel-HSM en exporteer de doelsleutel die wordt beveiligd door de KEK.
4. Importeer de beveiligde doelsleutel in Azure Key Vault.

Klanten gebruiken het BYOK-hulpprogramma en de documentatie van de HSM-leverancier om stap 3 te voltooien. Er wordt een sleuteloverdrachtblob (een .byok-bestand) geproduceerd.

HSM-beperkingen

Bestaande HSM's kunnen beperkingen toepassen op sleutel die ze beheren, waaronder:

• De HSM moet mogelijk worden geconfigureerd om export op basis van sleutelterugloop toe te staan
• De doelsleutel moet mogelijk worden gemarkeerd CKA_EXTRACTABLE voor de HSM om gecontroleerde export toe te staan
• In sommige gevallen moeten de KEK en de wrapping-sleutel mogelijk worden gemarkeerd als CKA_TRUSTED, waardoor deze kan worden gebruikt om sleutels in de HSM te verpakken.

De configuratie van de bron-HSM valt over het algemeen buiten het bereik van deze specificatie. Microsoft verwacht dat de HSM-leverancier documentatie levert bij het BYOK-hulpprogramma om dergelijke configuratiestappen op te nemen.

Notitie

Verschillende van deze stappen kunnen worden uitgevoerd met behulp van andere interfaces, zoals Azure PowerShell en Azure Portal. Ze kunnen ook programmatisch worden uitgevoerd met behulp van equivalente functies in Key Vault SDK.

KEK genereren

Gebruik de opdracht az keyvault key create om een KEK te maken met sleutelbewerkingen die zijn ingesteld voor importeren. Noteer de sleutel-id 'kind' die is geretourneerd door de onderstaande opdracht.

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

Notitie

Services ondersteunen verschillende KEK-lengten; Azure SQL ondersteunt bijvoorbeeld alleen sleutellengten van 2048 of 3072 bytes. Raadpleeg de documentatie voor uw service voor meer informatie.

De openbare sleutel van de KEK ophalen

Download het openbare sleutelgedeelte van de KEK en sla het op in een PEM-bestand.

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

Blob voor sleuteloverdracht genereren met behulp van het BYOK-hulpprogramma van de HSM-leverancier

De klant gebruikt het BYOK-hulpprogramma van de HSM-leverancier om een blob voor sleuteloverdracht te maken (opgeslagen als een .byok-bestand). De openbare KEK-sleutel (als pem-bestand) is een van de invoerwaarden voor dit hulpprogramma.

Sleuteloverdracht-blob

Op de lange termijn wil Microsoft pkcs#11 gebruiken CKM_RSA_AES_KEY_WRAP mechanisme om de doelsleutel over te dragen naar Azure Key Vault omdat dit mechanisme één blob produceert en, belangrijker, de tussenliggende AES-sleutel wordt verwerkt door de twee HSM's en gegarandeerd kortstondig is. Dit mechanisme is momenteel niet beschikbaar in sommige HSM's, maar de combinatie van het beveiligen van de doelsleutel met CKM_AES_KEY_WRAP_PAD het gebruik van een AES-sleutel en het beveiligen van de AES-sleutel met CKM_RSA_PKCS_OAEP produceert een equivalente blob.

De platte tekst van de doelsleutel is afhankelijk van het sleuteltype:

• Voor een RSA-sleutel, de persoonlijke sleutel ASN.1 DER-codering [RFC3447] verpakt in PKCS#8 [RFC5208]
• Voor een EC-sleutel, de persoonlijke sleutel ASN.1 DER encoding [RFC5915] verpakt in PKCS#8 [RFC5208]
• Voor een octetsleutel, de onbewerkte bytes van de sleutel

De bytes voor de sleutel voor tekst zonder opmaak worden vervolgens getransformeerd met behulp van het mechanisme CKM_RSA_AES_KEY_WRAP:

• Een kortstondige AES-sleutel wordt gegenereerd en versleuteld met de wrapping RSA-sleutel met behulp van RSA-OAEP met SHA1.
• De gecodeerde sleutel zonder tekst wordt versleuteld met behulp van de AES-sleutel met behulp van AES-sleutelterugloop met opvulling.
• De versleutelde AES-sleutel en de versleutelde sleutel zonder tekst zonder opmaak worden samengevoegd om de uiteindelijke coderings-blob te produceren.

De indeling van de overdrachtsblob gebruikt JSON Web Encryption compact serialisatie (RFC7516) voornamelijk als een voertuig voor het leveren van de vereiste metagegevens aan de service voor een juiste ontsleuteling.

Als CKM_RSA_AES_KEY_WRAP_PAD wordt gebruikt, is de JSON-serialisatie van de overdrachtsblob:

{
  "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 = sleutel-id van KEK. Voor Key Vault sleutels ziet dit er als volgt uit:https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
• alg = algoritme.
• dir = Directe modus, dat wil zeggen dat de kid waarnaar wordt verwezen, wordt gebruikt om de coderingstekst die een nauwkeurige weergave van CKM_RSA_AES_KEY_WRAP
• generator = een informatieveld dat de naam en versie van het BYOK-hulpprogramma en de bron-HSM-fabrikant en het model aandued. Deze informatie is bedoeld voor gebruik bij probleemoplossing en ondersteuning.

De JSON-blob wordt opgeslagen in een bestand met de extensie '.byok', zodat de Azure PowerShell-/CLI-clients deze correct behandelen wanneer 'Add-AzKeyVaultKey' (PSH) of 'az keyvault key import' (CLI) opdrachten worden gebruikt.

Blob voor sleuteloverdracht uploaden om HSM-sleutel te importeren

De klant brengt de Key Transfer Blob ('.byok'-bestand) over naar een onlinewerkstation en voert vervolgens een opdracht az keyvault key import uit om deze blob te importeren als een nieuwe sleutel met HSM-ondersteuning in Key Vault.

Gebruik deze opdracht om een RSA-sleutel te importeren:

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

Als u een EC-sleutel wilt importeren, moet u het sleuteltype en de curvenaam opgeven.

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

Wanneer de bovenstaande opdracht wordt uitgevoerd, wordt er als volgt een REST API-aanvraag verzonden:

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

Aanvraagbody bij het importeren van een RSA-sleutel:

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

Aanvraagtekst bij het importeren van een EC-sleutel:

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

De waarde 'key_hsm' is de volledige inhoud van de KeyTransferPackage-ContosoFirstHSMkey.byok gecodeerd in de Base64-indeling.

Referenties

• Gids voor Key Vault-ontwikkelaars

Volgende stappen

• Stapsgewijze BYOK-instructies: Met HSM beveiligde sleutels importeren in Key Vault (BYOK)