Specyfikacja używania własnego klucza

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

Scenariusz

Klient 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 Key Vault jest określany jako Bring Your Own Key (BYOK).

Poniżej przedstawiono wymagania:

  • Klucz do przeniesienia nigdy nie istnieje poza modułem HSM w postaci zwykłego tekstu.
  • Poza modułem HSM klucz do przeniesienia jest zawsze chroniony przez klucz przechowywany w module HSM platformy Azure Key Vault

Terminologia

Nazwa klucza Typ klucza Origin Opis
Klucz wymiany kluczy (KEK) RSA Moduł HSM usługi Azure Key Vault Para kluczy RSA z obsługą modułu HSM wygenerowana w usłudze Azure Key Vault
Zawijanie klucza AES Moduł HSM dostawcy Klucz AES wygenerowany przez moduł HSM lokalnie
Klucz docelowy RSA, EC, AES (tylko zarządzany moduł HSM) Moduł HSM dostawcy Klucz do przeniesienia 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)
  • Naprawiono key_ops (tylko "importowanie"), które umożliwią jej używanie tylko podczas stosowania funkcji BYOK
  • Musi znajdować się w tym samym magazynie, w którym zostanie zaimportowany klucz docelowy

Kroki użytkownika

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

  1. Generowanie klucza KEK.
  2. Pobierz klucz publiczny klucza kluczy publicznych.
  3. 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.
  4. 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 on 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 opakowujące mogą być oznaczone jako CKA_TRUSTED, co pozwala na opakowowanie kluczy w module HSM.

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

Uwaga

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

Generowanie klucza KEK

Użyj polecenia az keyvault key create , aby utworzyć klucz KEK z kluczem operacji ustawionych 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; Azure SQL, na przykład, 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 klucza kluczy publicznych

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, aby przenieść klucz docelowy na platformę Azure Key Vault, ponieważ ten mechanizm tworzy pojedynczy obiekt blob i, 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 przy użyciu 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 jest używana CKM_RSA_AES_KEY_WRAP_PAD, 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 klucza klucza. W przypadku kluczy Key Vault wygląda następująco:https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
  • alg = algorytm.
  • dir = tryb bezpośredni, czyli przywoływany dziecko jest używany do bezpośredniej ochrony szyfrowania tekstu, 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 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 do importowania klucza HSM-key

Klient przeniesie plik obiektu blob transferu kluczy (".byok" do stacji roboczej online, a następnie uruchomi polecenie az keyvault key import, aby zaimportować ten obiekt blob jako nowy klucz oparty na module HSM do 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.

Odwołania

Następne kroki