Import i eksport kluczy w OVHcloud KMS za pomocą BYOK

Wprowadzenie

Bring Your Own Key (BYOK) umożliwia import i eksport materiału kryptograficznego klucza w OVHcloud Key Management Service (KMS) bez przesyłania go w postaci jawnej. Para kluczy transportowych RSA chroni materiał w trakcie przesyłania: klucz publiczny go opakowuje, a tylko posiadacz klucza prywatnego może go rozpakować.

Ten przewodnik wyjaśnia, jak zaimportować i wyeksportować klucz w OVHcloud KMS przy użyciu asymetrycznego opakowywania kluczy RSA (BYOK).

Wymagania początkowe

• Konto klienta OVHcloud.
• Zamówiona usługa OVHcloud KMS.
• Skonfigurowana metoda uwierzytelniania dla płaszczyzny danych OKMS (osobisty token dostępu, konto serwisowe lub certyfikat dostępu).
• Możliwość zastosowania polityki IAM w domenie OKMS; wymagane akcje BYOK są wymienione w sekcji Konfiguracja IAM dla BYOK.
• Opcjonalnie: zainstalowane CLI OKMS lub SDK Go na potrzeby przykładów w kartach.

W praktyce

Zrozumienie ceremonii opakowywania RSA

Ceremonia obejmuje dwa środowiska i operatora:

• Miejsce docelowe (Dst): Twoja domena OKMS, w której zostanie przechowywany zaimportowany klucz.
• Źródło (Src): system, który obecnie przechowuje materiał klucza (inny KMS, aplikacja lub narzędzie takie jak OpenSSL).
• Operator: podmiot posiadający uprawnienia dostępu zarówno do domeny OKMS, jak i do źródła klucza do zaimportowania. Może to być osoba korzystająca z CLI OKMS lub usługa działająca poprzez API.

1. Wygeneruj parę kluczy transportowych RSA w OVHcloud KMS z operacjami wrapKey i unwrapKey.
2. Wyeksportuj publiczny klucz transportowy z OVHcloud KMS.
3. Zaimportuj publiczny klucz transportowy do środowiska źródłowego.
4. Po stronie źródła wyeksportuj materiał klucza opakowany (zaszyfrowany) kluczem transportowym, używając RSA-OAEP lub RSA-OAEP-256.
5. Po stronie miejsca docelowego zaimportuj opakowany klucz za pomocą POST /api/{okmsId}/v1/servicekey i ładunku wrappedKeys. KMS rozpakowuje ciphertext prywatnym kluczem transportowym i zapisuje wynikowy klucz serwisowy.

Klucze zaimportowane w ten sposób mają never_extractable ustawione na false, ponieważ materiał istniał poza KMS przed importem. Aby później wyodrębnić klucz w formie opakowanej, ustaw extractable na true i postępuj zgodnie z sekcją Eksport opakowanego klucza. Pełną listę atrybutów znajdziesz w sekcji Atrybuty wrażliwości kluczy serwisowych.

Konfiguracja IAM dla BYOK

Zastosuj politykę do zasobu swojej domeny OKMS. Jego URN jest wyświetlany w zakładce Informacje ogólne w dashboardzie Twojej domeny OKMS. Zastąp <identity_urn> i <okms_urn> swoimi wartościami. Utwórz polityki za pośrednictwem Panelu klienta OVHcloud lub API OVHcloud.

Import BYOK — odczyt, tworzenie lub import kluczy serwisowych oraz rozpakowywanie za pomocą klucza transportowego:

{
  "name": "okms-byok-import",
  "description": "Import wrapped keys into an OKMS domain using RSA BYOK",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apikms:serviceKey/get",
    "okms:apikms:serviceKey/create",
    "okms:apikms:serviceKey/unwrapKey",
    "okms:apikms:serviceKey/import"
  ]
}

Eksport BYOK — import publicznego klucza transportowego, aktualizacja możliwości wyodrębnienia oraz opakowanie klucza do eksportu:

{
  "name": "okms-byok-export",
  "description": "Export wrapped keys from an OKMS domain using RSA BYOK",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apikms:serviceKey/get",
    "okms:apikms:serviceKey/create",
    "okms:apikms:serviceKey/import",
    "okms:apikms:serviceKey/update",
    "okms:apikms:serviceKey/wrapKey"
  ]
}

Utworzenie klucza transportowego RSA w docelowym KMS

Utwórz klucz RSA przeznaczony do opakowywania. Na potrzeby ceremonii importu ustaw na tym kluczu zarówno wrapKey, jak i unwrapKey; wzajemnie wykluczają się one z sign i verify.

Obsługiwane rozmiary kluczy RSA: 2048, 3072 lub 4096 bitów.

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "byok-transport-rsa",
    "type": "RSA",
    "size": 4096,
    "operations": ["wrapKey", "unwrapKey"]
  }'

okms keys generate byok-transport-rsa \
  --type rsa \
  --size 4096 \
  --usage wrapKey,unwrapKey

resp, err := okmsClient.GenerateRSAKeyPair(
  ctx,
  okmsId,
  types.N4096,
  "byok-transport-rsa",
  types.SOFTWARE,
  "",
  []types.CryptographicUsages{types.WrapKey, types.UnwrapKey},
)
if err != nil {
  return err
}
transportKeyID := resp.Id

Zapisz zwrócone id klucza — potrzebujesz go jako wrappingKeyId podczas importu.

Pobranie publicznego klucza transportowego

Wyeksportuj publiczną część klucza transportowego i przekaż ją środowisku źródłowemu. Nigdy nie udostępniaj klucza prywatnego — pozostaje on wewnątrz docelowego KMS.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<transport-key-id>?format=jwk" \
  -H "Authorization: Bearer <token>"

okms keys export <transport-key-id> --format jwk

pub, err := okmsClient.ExportPublicKey(ctx, okmsId, transportKeyID)
if err != nil {
  return err
}
// pub to crypto.PublicKey (*rsa.PublicKey w przypadku klucza transportowego RSA)

jwk, err := okmsClient.ExportJwkPublicKey(ctx, okmsId, transportKeyID)
if err != nil {
  return err
}

Opakowanie materiału klucza źródłowego

W środowisku źródłowym zaszyfruj materiał klucza publicznym kluczem RSA miejsca docelowego.

Ten krok odbywa się poza OVHcloud KMS: w środowisku źródłowym użyj biblioteki JOSE.

Obsługiwane algorytmy opakowywania (RFC 7518):

keyFormatType opisuje format jawnego materiału klucza przed opakowaniem i po rozpakowaniu. Ciphertext jest zawsze ciągiem JWE Compact Serialization (algorytm opakowywania jest przenoszony w nagłówku JWE).

Po opakowaniu publicznym kluczem miejsca docelowego prześlij uzyskaną wartość ciphertext w formacie JWE Compact Serialization w żądaniu importu.

Import opakowanego klucza

Wywołaj POST /api/{okmsId}/v1/servicekey z tablicą wrappedKeys zamiast jawnych keys.

Każdy wpis wrappedKeys:

Możesz zaimportować sam klucz publiczny (class staje się PUBLIC_KEY) lub klucz prywatny (KMS odtwarza część publiczną; class staje się KEY_PAIR). Materiał symetryczny jest przechowywany jako SECRET_KEY.

Akcje IAM przy tym wywołaniu: okms:apikms:serviceKey/create, okms:apikms:serviceKey/import oraz okms:apikms:serviceKey/unwrapKey na kluczu transportowym.

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported-aes-byok",
    "operations": ["encrypt", "decrypt"],
    "wrappedKeys": [
      {
        "keyFormatType": "JWK",
        "wrappingKeyId": "<transport-key-id>",
        "ciphertext": "<jwe-compact-serialization>"
      }
    ]
  }'

okms keys import --usage encrypt,decrypt \
  --wrapping-key-id <transport-key-id> \
  --wrapped-key-format JWK \
  imported-aes-byok @wrapped.jwe

resp, err := okmsClient.ImportWrappedServiceKey(
  ctx,
  okmsId,
  transportKeyID,
  jweCompact,
  types.JWK,
  "imported-aes-byok",
  "",
  []types.CryptographicUsages{types.Encrypt, types.Decrypt},
)
if err != nil {
  return err
}
importedKeyID := resp.Id

Weryfikacja zaimportowanego klucza

Potwierdź, że klucz istnieje i odpowiada oczekiwanemu typowi oraz operacjom.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<imported-key-id>" \
  -H "Authorization: Bearer <token>"

okms keys get <imported-key-id>

key, err := okmsClient.GetServiceKey(ctx, okmsId, importedKeyID, nil)
if err != nil {
  return err
}

Sprawdź, czy:

• atrybut state klucza ma wartość active (lub aktywuj go, jeśli wymaga tego Twój przepływ pracy).
• type, size i operations odpowiadają Twoim założeniom.
• atrybuty wrażliwości w attributes odzwierciedlają zaimportowany klucz (never_extractable ma wartość false).

Następnie możesz używać klucza do operacji encrypt, decrypt, sign lub verify zgodnie z dokumentacją Korzystanie z OVHcloud Key Management Service (KMS).

Eksport opakowanego klucza

Bezpieczny eksport jest odwrotnością importu: OVHcloud KMS szyfruje materiał klucza kluczem transportowym RSA i zwraca wyłącznie ciphertext JWE. Prywatny klucz transportowy musi znajdować się w środowisku docelowym — czyli w systemie zewnętrznym, który otrzymuje klucz, a nie w OVHcloud KMS — aby tylko to środowisko mogło rozpakować materiał.

Zrozumienie ceremonii eksportu

1. Wygeneruj parę kluczy transportowych RSA w środowisku docelowym (inny KMS lub narzędzie, które odbierze klucz).
2. Zaimportuj publiczny klucz transportowy miejsca docelowego do OVHcloud KMS z operacją wrapKey (poziom ochrony SOFTWARE). Ten klucz to wrappingKeyId używany w momencie eksportu.
3. W OVHcloud KMS ustaw extractable na true na kluczu serwisowym tuż przed eksportem, a następnie wyeksportuj go opakowany tym kluczem transportowym. Następnie, gdy to możliwe, przywróć extractable do false.
4. Przenieś ciphertext do miejsca docelowego i rozpakuj go prywatnym kluczem transportowym miejsca docelowego.

Klucz transportowy wskazany przez wrappingKeyId musi być kluczem RSA SOFTWARE w tej samej domenie OKMS z użyciem wrapKey. Klucze wrażliwe (materiał AES/oct oraz prywatny materiał RSA/EC) można wyodrębnić tylko po opakowaniu — wyodrębnianie w postaci jawnej nie jest obsługiwane dla tych kluczy.

Import publicznego klucza transportowego miejsca docelowego do OVHcloud KMS

Zarejestruj publiczny klucz miejsca docelowego, aby OVHcloud KMS mógł nim opakować eksportowany klucz. Zaimportuj go jako klucz RSA wyłącznie publiczny z wrapKey (bez materiału prywatnego).

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "byok-export-transport-pub",
    "type": "RSA",
    "operations": ["wrapKey"],
    "keys": [
      {
        "kty": "RSA",
        "n": "<base64url-modulus>",
        "e": "<base64url-exponent>",
        "key_ops": ["wrapKey"]
      }
    ]
  }'

okms keys import byok-export-transport-pub @destination-transport-public.pem \
  --usage wrapKey

pemBytes, err := os.ReadFile("destination-transport-public.pem")
if err != nil {
  return err
}
resp, err := okmsClient.ImportKeyPairPEM(
  ctx,
  okmsId,
  pemBytes,
  "byok-export-transport-pub",
  "",
  []types.CryptographicUsages{types.WrapKey},
)
if err != nil {
  return err
}
wrappingKeyID := resp.Id

Zapisz zwrócone id klucza jako wrappingKeyId.

Włączenie wyodrębniania

Eksportowany klucz musi być możliwy do wyodrębnienia. Preferuj ustawienie extractable na true tylko na czas operacji eksportu (przez PATCH), a następnie przywrócenie wartości false. W miarę możliwości pozostawiaj klucze bez możliwości wyodrębnienia przy tworzeniu: ustawienie klucza jako możliwego do wyodrębnienia trwale ustawia never_extractable na false.

Akcja IAM: okms:apikms:serviceKey/update.

curl -X PATCH "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "extractable": true
  }'

okms keys update <key-id> --extractable=true

extractable := true
_, err := okmsClient.UpdateServiceKey(ctx, okmsId, keyID, types.PatchServiceKeyRequest{
  Extractable: &extractable,
})
if err != nil {
  return err
}

Po udanym eksporcie opakowanym (patrz sekcja Eksport klucza opakowanego kluczem transportowym) wyłącz ponownie wyodrębnianie:

curl -X PATCH "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "extractable": false
  }'

okms keys update <key-id> --extractable=false

extractable := false
_, err := okmsClient.UpdateServiceKey(ctx, okmsId, keyID, types.PatchServiceKeyRequest{
  Extractable: &extractable,
})
if err != nil {
  return err
}

Eksport klucza opakowanego kluczem transportowym

Wywołaj GET /api/{okmsId}/v1/servicekey/{keyId} z poniższymi parametrami zapytania opakowywania. Gdy te parametry są obecne, API zwraca wrappedKeys zamiast jawnych keys.

Akcje IAM: okms:apikms:serviceKey/get na eksportowanym kluczu oraz okms:apikms:serviceKey/wrapKey na kluczu transportowym.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>?wrappingKeyId=<wrapping-key-id>&wrappedKeyFormat=JWK&wrappingAlgorithm=RSA-OAEP-256" \
  -H "Authorization: Bearer <token>"

{
  "id": "<key-id>",
  "name": "imported-aes-byok",
  "type": "oct",
  "class": "SECRET_KEY",
  "size": 256,
  "operations": ["encrypt", "decrypt"],
  "wrappedKeys": [
    {
      "keyFormatType": "JWK",
      "wrappingKeyId": "<wrapping-key-id>",
      "ciphertext": "<jwe-compact-serialization>"
    }
  ]
}

okms keys get <key-id> \
  --wrapping-key-id <wrapping-key-id> \
  --wrapped-key-format JWK \
  --wrapping-algorithm RSA-OAEP-256

wrapped, err := okmsClient.GetWrappedServiceKey(
  ctx,
  okmsId,
  keyID,
  wrappingKeyID,
  types.JWK,
  types.RSAOAEP256,
)
if err != nil {
  return err
}
ciphertext := wrapped[0].Ciphertext

Rozpakowanie ciphertextu w miejscu docelowym

Przenieś ciphertext do środowiska docelowego. Rozpakuj go prywatnym kluczem transportowym miejsca docelowego (odpowiednikiem klucza publicznego zaimportowanego do OVHcloud KMS).

• Jeśli miejscem docelowym jest inna domena OKMS, zaimportuj tam opakowany materiał za pomocą wrappedKeys jak w Import opakowanego klucza, używając identyfikatora klucza transportowego tej domeny jako wrappingKeyId.
• Jeśli miejscem docelowym jest system zewnętrzny, użyj jego natywnego API rozpakowywania / importu z prywatnym kluczem transportowym oraz tym samym keyFormatType / algorytmem opakowywania, którego użyto przy eksporcie.

Sprawdź również

Korzystanie z OVHcloud Key Management Service (KMS)

Metody uwierzytelniania OKMS

Pierwsze kroki z OVHcloud Key Management Service (KMS)

Dołącz do grona naszych użytkowników.