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 wil een sleutel veilig overdragen van hun on-premises HSM buiten Azure, naar de HSM-backing van Azure Key Vault. Het proces voor het importeren van een sleutel die buiten Key Vault wordt gegenereerd, wordt BYOK (Bring Your Own Key) genoemd.

Hier volgen de volgende 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	Oorprong	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 HSM on-premises
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 'import'), waardoor deze ALLEEN kan worden gebruikt tijdens BYOK
• Moet zich in dezelfde kluis bevinden waar de doelsleutel wordt geïmporteerd

Gebruikersstappen

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

1. Genereer KEK.
2. Haal de openbare sleutel van de KEK op.
3. Met behulp van de HSM-leverancier die byok is geleverd: importeer de KEK in de doel-HSM en exporteert 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. Het produceert een sleuteloverdrachtblob (een byok-bestand).

HSM-beperkingen

Bestaande HSM kan beperkingen toepassen op de 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 moet de KEK- en wrapping-sleutel mogelijk worden gemarkeerd als CKA_TRUSTED, zodat 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 produceert die bij hun BYOK-hulpprogramma hoort, zodat deze configuratiestappen moeten worden opgenomen.

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 KEK te maken met sleutelbewerkingen die zijn ingesteld om te importeren. Noteer de sleutel-id 'kid' 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 specifieke informatie.

De openbare sleutel van de KEK ophalen

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

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

Sleuteloverdrachtblob genereren met behulp van het BYOK-hulpprogramma van de HSM-leverancier

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

Sleuteloverdrachtblob

Op lange termijn wil Microsoft PKCS#11 CKM_RSA_AES_KEY_WRAP-mechanisme gebruiken 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 met behulp van een AES-sleutel en het beveiligen van de AES-sleutel met CKM_RSA_PKCS_OAEP produceert een equivalente blob.

De doelsleutel zonder opmaak is afhankelijk van het sleuteltype:

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

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

• Er wordt een kortstondige AES-sleutel gegenereerd en versleuteld met de wrapping RSA-sleutel met behulp van RSA-OAEP met SHA1.
• De gecodeerde sleutel voor tekst zonder opmaak wordt versleuteld met behulp van de AES-sleutel met behulp van AES Key Wrap met opvulling.
• De versleutelde AES-sleutel en de versleutelde sleutel voor tekst zonder opmaak worden samengevoegd om de uiteindelijke ciphertext-blob te produceren.

De indeling van de overdrachtsblob maakt gebruik van compacte serialisatie van JSON Web Encryption (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 = key identifier of KEK. Voor Key Vault-sleutels ziet dit er als volgt uit: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
• alg = algoritme.
• dir = Directe modus, d.w.w.v. het kind waarnaar wordt verwezen, wordt gebruikt om de coderingstekst die een nauwkeurige weergave is 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 aangeeft. Deze informatie is bedoeld voor 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 blob voor sleuteloverdracht (.byok) over naar een onlinewerkstation en voert vervolgens een az keyvault key import-opdracht uit om deze blob te importeren als een nieuwe sleutel met HSM-ondersteuning in Key Vault.

Als u een RSA-sleutel wilt importeren, gebruikt u deze opdracht:

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, resulteert dit in het verzenden van een REST API-aanvraag als volgt:

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
  }
}

Aanvraagbody 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.

Verwijzingen

• Gids voor Key Vault-ontwikkelaars

Volgende stappen

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