Specyfikacja używania własnego klucza

Artykuł
08/07/2024

W tym dokumencie opisano specyfikacje dotyczące importowania kluczy chronionych przez moduł HSM z lokalnych modułów HSM klientów do usługi Key Vault.

Scenariusz

Klient usługi Key Vault chce bezpiecznie przenieść klucz z lokalnego modułu HSM spoza platformy Azure do modułu HSM opartego na usłudze Azure Key Vault. Proces importowania klucza wygenerowanego poza usługą Key Vault jest określany jako Bring Your Own Key (BYOK).

Poniżej przedstawiono wymagania:

Klucz, który ma zostać przeniesiony, nigdy nie istnieje poza modułem HSM w postaci zwykłego tekstu.
Poza modułem HSM klucz, który ma zostać przeniesiony, jest zawsze chroniony przez klucz przechowywany w module HSM usługi Azure Key Vault

Terminologia

Nazwa klucza	Typ klucza	Pochodzenie	opis
Klucz wymiany kluczy (KEK)	RSA	Karta HSM usługi Azure Key Vault	Para kluczy RSA z obsługą modułu HSM wygenerowana w usłudze Azure Key Vault
Klucz zawijania	AES	Moduł HSM dostawcy	[efemeryczne] Klucz AES wygenerowany przez lokalny moduł HSM
Klucz docelowy	RSA, EC, AES (tylko zarządzany moduł HSM)	Moduł HSM dostawcy	Klucz, który ma zostać przeniesiony do modułu HSM usługi Azure Key Vault

Klucz wymiany kluczy: klucz oparty na module HSM generowany przez klienta w magazynie kluczy, w którym zostanie zaimportowany klucz BYOK. Ten klucz KEK musi mieć następujące właściwości:

Jest to klucz RSA-HSM (4096-bitowy lub 3072-bitowy lub 2048-bitowy)
Będzie on miał stały key_ops (tylko "import"), który pozwoli na jego używanie tylko podczas BYOK
Musi znajdować się w tym samym magazynie, w którym zostanie zaimportowany klucz docelowy

Kroki użytkownika

Aby wykonać transfer klucza, użytkownik wykonuje następujące czynności:

Generowanie klucza KEK.
Pobierz klucz publiczny klucza KEK.
Użycie dostawcy MODUŁU HSM dostarczonego przez narzędzie BYOK — zaimportuj klucz KEK do docelowego modułu HSM i eksportuje klucz docelowy chroniony przez klucz KEK.
Zaimportuj chroniony klucz docelowy do usługi Azure Key Vault.

Klienci używają narzędzia BYOK i dokumentacji dostarczonej przez dostawcę modułu HSM, aby wykonać kroki 3. Tworzy obiekt blob transferu kluczy (plik ".byok").

Ograniczenia modułu HSM

Istniejący moduł HSM może stosować ograniczenia dotyczące klucza, którymi zarządzają, w tym:

Może być konieczne skonfigurowanie modułu HSM w celu zezwolenia na eksportowanie oparte na zawijanie kluczy
Może być konieczne oznaczenie klucza docelowego CKA_EXTRACTABLE dla modułu HSM w celu umożliwienia kontrolowanego eksportu
W niektórych przypadkach klucz KEK i klucz opakowujące mogą być oznaczone jako CKA_TRUSTED, co umożliwia jego użycie do opakowowania kluczy w module HSM.

Konfiguracja źródłowego modułu HSM jest ogólnie spoza zakresu tej specyfikacji. Firma Microsoft oczekuje, że dostawca modułu HSM utworzy dokumentację dołączącą do narzędzia BYOK, aby uwzględnił wszelkie takie kroki konfiguracji.

Uwaga

Kilka z tych kroków można wykonać przy użyciu innych interfejsów, takich jak program Azure PowerShell i witryna Azure Portal. Można je również wykonywać programowo przy użyciu równoważnych funkcji w zestawie SDK usługi Key Vault.

Generowanie klucza KEK

Użyj polecenia az keyvault key create, aby utworzyć klucz KEK z kluczami ustawionymi na import. Zanotuj identyfikator klucza "kid" zwrócony z poniższego polecenia.

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

Uwaga

Usługi obsługują różne długości klucza KEK; Na przykład usługa Azure SQL obsługuje tylko długości kluczy 2048 lub 3072 bajtów. Zapoznaj się z dokumentacją usługi, aby uzyskać szczegółowe informacje.

Pobieranie klucza publicznego klucza szyfrowania kluczy

Pobierz część klucza publicznego klucza kluczy publicznych i zapisz ją w pliku PEM.

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

Generowanie obiektu blob transferu kluczy przy użyciu dostawcy modułu HSM dostarczonego przez narzędzie BYOK

Klient użyje dostawcy modułu HSM dostarczonego przez narzędzie BYOK do utworzenia obiektu blob transferu kluczy (przechowywanego jako plik ".byok"). Klucz publiczny KEK (jako plik pem) będzie jednym z danych wejściowych tego narzędzia.

Obiekt blob transferu kluczy

W dłuższej perspektywie firma Microsoft chce użyć mechanizmu PKCS#11 CKM_RSA_AES_KEY_WRAP w celu przeniesienia klucza docelowego do usługi Azure Key Vault, ponieważ ten mechanizm tworzy pojedynczy obiekt blob, a co ważniejsze, pośredni klucz AES jest obsługiwany przez dwa moduły HSM i ma gwarancję efemerycznego. Ten mechanizm nie jest obecnie dostępny w niektórych modułach HSM, ale kombinacja ochrony klucza docelowego przy użyciu CKM_AES_KEY_WRAP_PAD przy użyciu klucza AES i ochrony klucza AES za pomocą CKM_RSA_PKCS_OAEP tworzy równoważny obiekt blob.

Klucz docelowy w postaci zwykłego tekstu zależy od typu klucza:

W przypadku klucza RSA kodowanie ASN.1 DER klucza prywatnego [RFC3447] opakowane w PKCS#8 [RFC5208]
W przypadku klucza EC kodowanie ASN.1 DER klucza prywatnego [RFC5915] opakowane w PKCS#8 [RFC5208]
W przypadku klucza oktetu nieprzetworzone bajty klucza

Bajty klucza zwykłego tekstu są następnie przekształcane przy użyciu mechanizmu CKM_RSA_AES_KEY_WRAP:

Efemeryczny klucz AES jest generowany i szyfrowany za pomocą opakowującego klucza RSA przy użyciu protokołu RSA-OAEP z algorytmem SHA1.
Zakodowany klucz zwykłego tekstu jest szyfrowany przy użyciu klucza AES przy użyciu zawijania klucza AES z wypełnieniem.
Zaszyfrowany klucz AES i zaszyfrowany klucz zwykłego tekstu są łączone w celu utworzenia końcowego obiektu blob szyfrowania.

Format transferu obiektu blob używa kompaktowej serializacji JSON Web Encryption (RFC7516) głównie jako pojazdu do dostarczania wymaganych metadanych do usługi w celu poprawnego odszyfrowywania.

Jeśli CKM_RSA_AES_KEY_WRAP_PAD jest używana, serializacja JSON obiektu blob transferu będzie:

{
  "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 = identyfikator klucza KEK. W przypadku kluczy usługi Key Vault wygląda następująco: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
alg = algorytm.
dir = tryb bezpośredni, czyli, przywoływany dzieciak jest używany do bezpośredniej ochrony szyfrowania, który jest dokładną reprezentacją CKM_RSA_AES_KEY_WRAP
generator = pole informacyjne, które określa nazwę i wersję narzędzia BYOK oraz producenta i modelu źródłowego modułu HSM. Te informacje są przeznaczone do użycia w rozwiązywaniu problemów i obsłudze technicznej.

Obiekt blob JSON jest przechowywany w pliku z rozszerzeniem "byok", dzięki czemu klienci programu Azure PowerShell/interfejsu wiersza polecenia traktują go poprawnie, gdy są używane polecenia "Add-AzKeyVaultKey" (PSH) lub "az keyvault key import" (CLI).

Przekazywanie obiektu blob transferu kluczy w celu zaimportowania klucza HSM

Klient przetransferuje plik obiektu blob transferu kluczy (".byok) na stację roboczą online, a następnie uruchomi polecenie az keyvault key import , aby zaimportować ten obiekt blob jako nowy klucz oparty na module HSM do usługi Key Vault.

Aby zaimportować klucz RSA, użyj następującego polecenia:

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

Aby zaimportować klucz EC, należy określić typ klucza i nazwę krzywej.

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

Po wykonaniu powyższego polecenia powoduje wysłanie żądania interfejsu API REST w następujący sposób:

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

Treść żądania podczas importowania klucza RSA:

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

Treść żądania podczas importowania klucza EC:

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

Wartość "key_hsm" to cała zawartość klucza KeyTransferPackage-ContosoFirstHSMkey.byok zakodowana w formacie Base64.

Informacje

Przewodnik dewelopera usługi Key Vault

Następne kroki

Instrukcje krok po kroku BYOK: Importowanie kluczy chronionych przez moduł HSM do usługi Key Vault (BYOK)

Udostępnij za pośrednictwem