Specifikace vlastního klíče

2025-06-17

Tento dokument popisuje specifikace pro import klíčů chráněných HSM z místních hsM zákazníků do služby Key Vault.

Scénář

Zákazník služby Key Vault chce bezpečně přenést klíč ze svého místního HSM mimo Azure do HSM, které podporuje Azure Key Vault. Proces importu klíče vygenerovaného mimo službu Key Vault se označuje jako ByOK (Bring Your Own Key).

Toto jsou požadavky:

Klíč, který se má přenést, nikdy neexistuje mimo HSM ve formě prostého textu.
Mimo hsm je klíč, který se má přenést, vždy chráněný klíčem uloženým v HSM služby Azure Key Vault.

Terminologie

Název klíče	Typ klávesy	Původ	Popis
Klíč výměny klíčů (KEK)	RSA	Azure Key Vault HSM	Pár klíčů RSA založený na HSM vygenerovaný ve službě Azure Key Vault
Obtékání klíče	AES	Modul hardwarového zabezpečení (HSM dodavatele)	[dočasný] klíč AES vygenerovaný místním modulem HSM
Cílový klíč	RSA, EC, AES (pouze spravovaný HSM)	Modul hardwarového zabezpečení (HSM dodavatele)	Klíč, který se má přenést do HSM služby Azure Key Vault

Klíč výměny klíčů: Klíč založený na HSM, který zákazník vygeneruje v trezoru klíčů, kde je importován klíč BYOK. Tento klíč KEK musí mít následující vlastnosti:

Je to klíč RSA-HSM (4096bitová nebo 3072bitová nebo 2048bitová verze).
Má pevně stanovené key_ops (ONLY import), které umožňuje jeho využití pouze během BYOK.
Musí být ve stejném trezoru, ve kterém je importovaný cílový klíč.

Kroky uživatele

Pokud chcete provést přenos klíče, uživatel provede následující kroky:

Vygenerujte klíč KEK.
Načtěte veřejný klíč šifrovacího klíče KEK.
Použití nástroje BYOK od dodavatele HSM – Import klíče KEK do cílového HSM a exportování cílového klíče chráněného klíčem KEK.
Naimportujte chráněný cílový klíč do služby Azure Key Vault.

Zákazníci k dokončení kroků 3 používají nástroj BYOK a dokumentaci od dodavatele HSM. Vytváří soubor blob pro přenesení klíčů (soubor ".byok").

Omezení HSM

Stávající HSM může používat omezení klíče, které spravují, včetně:

HsM může být potřeba nakonfigurovat tak, aby povoloval export založený na zalamování klíčů.
Cílový klíč může být potřeba označit CKA_EXTRACTABLE pro HSM, aby bylo možné řídit export.
V některých případech může být potřeba označit KEK a obalovací klíč jako CKA_TRUSTED, což umožňuje použít je k zabalení klíčů v HSM.

Konfigurace zdrojového HSM je obecně mimo rozsah této specifikace. Společnost Microsoft očekává, že dodavatel HSM vytvoří dokumentaci, která doprovází nástroj BYOK, aby zahrnoval všechny takové kroky konfigurace.

Poznámka:

Několik z těchto kroků je možné provést pomocí jiných rozhraní, jako je Azure PowerShell a Azure Portal. Dají se také provádět programově pomocí ekvivalentních funkcí v sadě Key Vault SDK.

Vygenerovat KEK

Pomocí příkazu az keyvault key create vytvořte klíč KEK, u kterého jsou operace klíče nastaveny na import. Poznamenejte si identifikátor klíče "kid" vrácený z tohoto příkazu.

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

Poznámka:

Služby podporují různé délky KEK; Azure SQL například podporuje jenom délky klíčů 2048 nebo 3072 bajtů. Konkrétní informace najdete v dokumentaci k vaší službě.

Načtěte veřejný klíč KEK

Stáhněte část veřejného klíče KEK a uložte ji do souboru PEM.

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

Vytvoření blobu pro přenos klíčů pomocí nástroje BYOK od dodavatele HSM

Zákazník používá k vytvoření objektu blob pro přenos klíčů (uložený jako soubor .byok) nástroj BYOK od dodavatele HSM. Veřejný klíč KEK (jako soubor .pem) je jedním ze vstupů tohoto nástroje.

Přenosový blob klíčů

Společnost Microsoft by dlouhodobě chtěla k přenosu cílového klíče do služby Azure Key Vault použít mechanismus PKCS#11 CKM_RSA_AES_KEY_WRAP, protože tento mechanismus vytváří jeden objekt blob a co je důležitější, zprostředkující klíč AES zpracovávají dva moduly hardwarového zabezpečení (HSM) a je zaručeno, že je dočasný. Tento mechanismus není v některých modulech HSM k dispozici, ale kombinace ochrany cílového klíče algoritmem CKM_AES_KEY_WRAP_PAD pomocí klíče AES a ochrany klíče AES algoritmem CKM_RSA_PKCS_OAEP vytvoří ekvivalentní datový objekt.

Prostý text cílového klíče závisí na typu klíče:

U klíče RSA je kódování ASN.1 DER privátního klíče [RFC3447] zabalené v PKCS#8 [RFC5208]
Pro klíč EC je kódování soukromého klíče ASN.1 DER [RFC5915] zabalené v PKCS#8 [RFC5208]
Pro osmibajtový klíč jsou to nezpracované bajty klíče.

Bajty klíče prostého textu se pak transformují pomocí mechanismu CKM_RSA_AES_KEY_WRAP:

Dočasný klíč AES se vygeneruje a zašifruje pomocí obaleného klíče RSA s použitím RSA-OAEP a SHA1.
Kódovaný klíč prostého textu je šifrován pomocí klíče AES při použití metody AES Key Wrap s paddingem.
Šifrovaný klíč AES a šifrovaný klíč prostého textu jsou zřetězeny, aby se vytvořil konečný objekt blob šifrového textu.

Formát přenosového objektu blob používá kompaktní serializaci JSON Web Encryption (RFC7516) primárně jako prostředek pro doručování požadovaných metadat do služby pro správné dešifrování.

Pokud CKM_RSA_AES_KEY_WRAP_PAD použijete, serializace JSON objektu blob přenosu bude následující:

{
  "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 = identifikátor šifrovacího klíče KEK. U klíčů Key Vaultu to vypadá takto: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
alg = algoritmus.
dir = přímý režim, to znamená, že odkazovaný klíč se používá k přímé ochraně zašifrovaného textu, který je přesné zobrazení CKM_RSA_AES_KEY_WRAP
generator = informační pole, které označuje název a verzi nástroje BYOK a výrobce a model zdrojového HSM. Tyto informace jsou určené k řešení potíží a podpoře.

Objekt JSON typu blob je uložený v souboru s příponou ".byok", aby jej Azure PowerShell nebo klient CLI zpracovávaly správně při použití příkazů 'Add-AzKeyVaultKey' (PowerShell) nebo 'az keyvault key import' (CLI).

Nahrání objektu blob přenosu klíčů pro import klíče HSM

Zákazníci přenesou objekt blob pro přenos klíčů (soubor .byok) do online pracovní stanice a potom spustí příkaz az keyvault key import k importu tohoto objektu blob jako nového klíče založeného na HSM do služby Key Vault.

K importu klíče RSA použijte tento příkaz:

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

Chcete-li importovat klíč EC, je nutné zadat typ klíče a název křivky.

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

Když se tento příkaz spustí, výsledkem je odeslání požadavku rozhraní REST API následujícím způsobem:

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

Text požadavku při importu klíče RSA:

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

Text požadavku při importu klíče EC:

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

Hodnota "key_hsm" je celý obsah KeyTransferPackage-ContosoFirstHSMkey.byok kódovaný ve formátu Base64.

Odkazy

Průvodce vývojáře pro službu Key Vault

Další kroky

Podrobné pokyny k BYOK: Import klíčů chráněných HSM do služby Key Vault (BYOK)