Korzystanie z OVHcloud Key Management Service (KMS)

Wprowadzenie

Celem tego przewodnika jest przedstawienie kolejnych etapów interakcji z KMS OVHcloud w celu szyfrowania lub podpisywania danych.

Wymagania początkowe

• Posiadanie konta klienta OVHcloud.
• Zamówienie KMS OVHcloud.
• Skonfigurowanie metody uwierzytelniania dla płaszczyzny danych OKMS (osobisty token dostępu, konto serwisowe lub certyfikat dostępu).

W praktyce

Komunikacja z KMS

Komunikacja z KMS w celu wykonania operacji szyfrowania i podpisywania odbywa się za pośrednictwem API.

Ponieważ KMS jest zregionalizowany, dostęp do API odbywa się bezpośrednio w jego regionie: https://my-region.okms.ovh.net.

Na przykład dla KMS utworzonego w regionie eu-west-rbx: https://eu-west-rbx.okms.ovh.net.

Komunikacja z KMS jest możliwa przy użyciu:

• Interfejsu użytkownika Swagger
• CLI OKMS: https://github.com/ovh/okms-cli
• SDK Golang: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Uwierzytelnij się za pomocą osobistego tokenu dostępu, konta serwisowego lub certyfikatu dostępu. W przypadku korzystania z API REST zalecany jest osobisty token dostępu (PAT) lub konto serwisowe. Certyfikaty dostępu są wymagane w przypadku integracji KMIP.

Aby testować wywołania API w sposób interaktywny, użyj interfejsu Swagger OKMS pod adresem https://<region>.okms.ovh.net/swagger/.

Tworzenie klucza szyfrującego przez API

Utworzenie klucza może odbyć się za pomocą API OVHcloud lub za pomocą API właściwych dla KMS OVHcloud. Wynik nie różni się w zależności od metody tworzenia.

W przypadku API właściwych dla KMS OVHcloud utworzenie klucza odbywa się za pomocą następującego API:

API oczekuje następujących wartości:

Przykład tworzenia klucza symetrycznego:

{
  "name": "My first AES key",
  "context": "project A",
  "type": "oct",
  "size": 256,
  "operations": [
    "encrypt",
    "decrypt"
  ]
}

Przykład tworzenia klucza asymetrycznego:

{
  "name": "My first RSA key",
  "context": "project A",
  "type": "RSA",
  "size": 4096,
  "operations": [
    "sign",
    "verify"
  ]
}

Przykład tworzenia klucza EC:

{
  "name": "My first EC key",
  "context": "project A",
  "type": "EC",
  "operations": [
    "sign",
    "verify"
  ],
  "curve": "P-256"
}

Przykład tworzenia klucza chronionego przez HSM:

{
  "name": "My HSM-backed AES key",
  "context": "project A",
  "type": "oct",
  "size": 256,
  "protectionLevel": "HSM",
  "operations": [
    "encrypt",
    "decrypt"
  ]
}

W zależności od typu klucza możliwe rozmiary i operacje są następujące:

• Oct:
  • rozmiar: 128, 192, 256
  • operacje:
    • encrypt, decrypt
    • wrapKey, unwrapKey
• RSA:
  • rozmiar: 2048, 3072, 4096
  • operacje:
    • sign, verify
    • wrapKey, unwrapKey
• EC:
  • rozmiar: nie określać
  • curve: P-256, P-384, P-521
  • operacje: sign, verify

Importowanie klucza szyfrującego

Podczas tworzenia klucza możesz zaimportować istniejący klucz w postaci jawnej w formacie JWK.

W tym celu możesz dodać dodatkowe pole keys w treści żądania:

{
  "name": "My imported key",
  "keys": [
    {
      "kid": "string",
      "use": "string",
      "key_ops": [
        "string"
      ],
      "alg": "string",
      "kty": "oct",
      "n": "string",
      "e": "string",
      "k": "string",
      "crv": "string",
      "x": "string",
      "y": "string",
      "d": "string",
      "dp": "string",
      "dq": "string",
      "p": "string",
      "q": "string",
      "qi": "string"
    }
  ]
}

Klucz musi być w formacie JSON Web Key (JWK). Wartości pól zawartych w tabeli są zgodne z dokumentacją RFC 7518.

Zarządzanie kluczami szyfrującymi

Do zarządzania kluczami szyfrującymi dostępnych jest kilka API:

Klucze są tworzone lub importowane bezpośrednio w stanie active. Dezaktywacja klucza uniemożliwia jego użycie kryptograficzne, ale klucz pozostaje w KMS. Usunąć można wyłącznie klucz w stanie deactivated lub compromised.

Operacje dozwolone w każdym stanie znajdziesz w sekcji Stany kluczy serwisowych i dozwolone operacje.

Stany kluczy serwisowych i dozwolone operacje

Stan klucza serwisowego określa, które operacje akceptuje KMS, zgodnie z modelami cyklu życia kluczy zdefiniowanymi w KMIP 2.1 i NIST SP 800-57:

• Klucz active może być używany do każdej operacji kryptograficznej wymienionej w jego polu operations.
• Klucz deactivated lub compromised nie akceptuje operacji kryptograficznych. Nie może już chronić danych (encrypt, sign, opakowywać, generować Data Keys), odzyskiwać ich (decrypt, odpakowywać Data Keys) ani weryfikować podpisów. Operacje zarządzania (odczyt, wyświetlanie listy, patch, aktywacja, dezaktywacja, usunięcie) pozostają dostępne.
• Po DELETE klucz zostaje trwale usunięty: każde późniejsze żądanie dotyczące tego identyfikatora klucza zwraca 404 Not Found.

Zmiany stanu obowiązują natychmiast, bez opóźnienia propagacji: każde żądanie otrzymane po udanym activate, deactivate lub DELETE jest oceniane względem nowego stanu.

Atrybuty wrażliwości kluczy serwisowych

Gdy tworzysz lub pobierasz klucz serwisowy, flagi wrażliwości i możliwości wyodrębnienia są zwracane w obiekcie attributes odpowiedzi GET (obok innych metadanych, takich jak state). Tylko extractable może być ustawiane przez użytkownika (przy tworzeniu lub przez PATCH). Pozostałe flagi ustawia KMS. Ustawienie extractable na true trwale ustawia never_extractable na false.

Przykładowa odpowiedź GET (pola skrócone):

{
  "id": "<key-id>",
  "name": "aes-to-export",
  "type": "oct",
  "attributes": {
    "state": "active",
    "extractable": true,
    "never_extractable": false,
    "sensitive": true,
    "always_sensitive": true
  }
}

Aby bezpiecznie wyodrębnić klucz, ustaw extractable na true tylko na czas operacji eksportu, wyeksportuj go z opakowaniem RSA, a następnie przywróć wartość false. Informacje znajdziesz w sekcji Eksport opakowanego klucza.

Szyfrowanie danych za pomocą KMS

Szyfrowanie w KMS

KMS OVHcloud dysponuje dedykowanym API szyfrowania przeznaczonym do szyfrowania małych ilości danych (mniej niż 4 kB).

Jest to najprostsza metoda, która jednak nie zapewnia najlepszej wydajności.

API oczekuje następujących wartości:

Przykład szyfrowania

{
  "plaintext": "My secret data",
  "context": "Project A"
}

Następnie API zwraca zaszyfrowane dane w polu ciphertext:

{
  "ciphertext": "Encrypted data",
}

Deszyfrowanie danych odbywa się w sposób odwrotny za pomocą API:

API oczekuje następujących wartości:

Pole context musi mieć taką samą wartość jak ta podana podczas szyfrowania.

Szyfrowanie za pomocą Data Key (DK)

Aby uzyskać większą wydajność, możesz wygenerować Data Key (DK) na podstawie klucza symetrycznego (AES), aby używać go z poziomu swojej aplikacji. Wykorzystywany klucz AES musi zostać wygenerowany z operacjami wrapKey i unwrapKey.

Wygenerowanie DK odbywa się za pomocą następującego API:

API oczekuje następujących wartości:

Przykład generowania Data Key:

{
  "name": "My Data Key",
  "size": 4096
}

Następnie API zwróci Data Key:

{
  "key": "string",
  "plaintext": "string"
}

• key: zaszyfrowany klucz zakodowany w base64. Ta informacja musi być przechowywana wraz z zaszyfrowanymi danymi i będzie używana do deszyfrowania przez KMS.
• plaintext: klucz jawny zakodowany w base64. Ta informacja musi zostać usunięta po zakończeniu szyfrowania i nie może być zapisywana w kopii zapasowej.

Wykorzystanie Data Key odbywa się następnie za pomocą algorytmów szyfrowania takich jak AES-GCM, który nie jest omawiany w niniejszej dokumentacji.

Odwrotnie, możesz pobrać zdeszyfrowaną wersję Data Key za pomocą następującego API:

API oczekuje następujących wartości:

I zwraca zdeszyfrowany Data Key w polu plaintext.

Podpisywanie za pomocą KMS

Podpisywanie pliku odbywa się za pomocą klucza prywatnego z pary kluczy asymetrycznych.

Obsługiwane algorytmy

KMS OVHcloud obsługuje następującą listę algorytmów podpisywania:

• RSASSA-PKCS1 v1.5

Zgodnie z dokumentacją RFC 7518.

• ECDSA

Zgodnie z dokumentacją RFC 7518.

• RSASSA-PSS

Zgodnie z dokumentacją RFC 7518.

Podpisywanie wiadomości

Ponieważ klucza prywatnego nie można wyodrębnić z KMS w postaci jawnej, podpisywanie może odbywać się wyłącznie bezpośrednio w KMS.

API oczekuje następujących wartości:

Przykład podpisywania:

{
  "message": "SGVsbG8gV29ybGQ=",
  "alg": "RS256",
  "isdigest": false
}

Następnie API zwróci podpis pliku:

{
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw=="
}

Weryfikacja pliku

Weryfikacja pliku może odbywać się bezpośrednio w KMS lub przy użyciu klucza publicznego.

W KMS możesz użyć następującego API:

API oczekuje następujących wartości:

Przykład weryfikacji

{
  "message": "SGVsbG8gV29ybGQ=",
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw==",
  "alg": "RS256",
  "isdigest": false
}

Następnie API zwróci wynik weryfikacji:

{
  "result": true
}

Sprawdź również

Import i eksport kluczy w OVHcloud KMS za pomocą BYOK

Metody uwierzytelniania OKMS

Jak połączyć zgodny produkt za pomocą protokołu KMIP

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