Zarządzanie plikami zaszyfrowanymi po stronie klienta za pomocą interfejsu Drive API

Szyfrowanie po stronie klienta zapewnia, że dane są szyfrowane, zanim trafią na serwery Dysku, co daje Ci kontrolę nad danymi. Ten przewodnik przeprowadzi Cię przez proces programowego szyfrowania i przesyłania oraz pobierania i odszyfrowywania plików zaszyfrowanych po stronie klienta za pomocą interfejsu Drive API. Zawiera też zalecane podejścia do testowania i weryfikowania implementacji.

Zanim zaczniesz

Zanim zaczniesz zarządzać zaszyfrowanymi plikami, skonfiguruj domenę Google Workspace, korzystając z tej listy kontrolnej:

Uwierzytelnianie i autoryzacja

Aby korzystać z interfejsu Drive API i KACLS, musisz wybrać metodę uwierzytelniania. Ten wybór wpływa na sposób korzystania z obu usług:

Więcej informacji o tworzeniu danych logowania znajdziesz w przewodniku Tworzenie danych logowania.

Uwierzytelnianie dostawcy tożsamości domeny

Aby uwierzytelnić się u dostawcy tożsamości, musisz skonfigurować identyfikator klienta OAuth i pobrać plik tajnego klucza klienta. Aplikacja musi uzyskać token uwierzytelniania od dostawcy tożsamości, aby uwierzytelniać żądania wysyłane do KACLS. Ten token jest wymagany, aby umożliwić aplikacji dostęp do klucza szyfrowania danych.

Bezpieczne zarządzanie danymi logowania

Aplikacja obsługuje poufne dane logowania do uwierzytelniania w interfejsie Drive API i dostawcy tożsamości. Obejmują one:

  • tajne materiały od dostawcy tożsamości, np. plik z tajnym kluczem klienta;
  • tajne materiały Google, takie jak plik klucza prywatnego konta usługi;
  • tajne materiały przechowywane przez aplikację, np. zapisane dane logowania;

Musisz zadbać o bezpieczne przechowywanie wszystkich tych danych logowania.

Limity i przydziały

Pliki zaszyfrowane po stronie klienta podlegają standardowym limitom i kwotom Dysku. Zapoznaj się z limitami dysków współdzielonych, ogólnymi limitami plików i folderów oraz dowiedz się, jak zarządzać limitem miejsca. Dodatkowo narzędzie do importowania musi obsługiwać limity szybkości z usługi listy kontroli dostępu do kluczy (KACLS) i dostawcy tożsamości.

Struktura zaszyfrowanego pliku

Dysk oczekuje następującego formatu pliku zaszyfrowanego po stronie klienta w przypadku przesyłania i pobierania.

+-------------------+
| Magic header      |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ...               |
+-------------------+
| Encrypted Chunk N |
+-------------------+

Magiczny nagłówek

Nagłówek magiczny (znany też jako sygnatura pliku lub liczba magiczna) to stała sekwencja bajtów umieszczana na samym początku pliku, aby jednoznacznie zidentyfikować jego format. Plik musi zaczynać się od bajtów 0x99 0x5E 0xCC 0x5E.

Zaszyfrowane fragmenty

Plik musi być podzielony na części o rozmiarze 2 MiB. Każdy fragment jest szyfrowany za pomocą prymitywu uwierzytelnionego szyfrowania z danymi powiązanymi (AEAD) z biblioteki Google Tink z użyciem typu klucza AES-GCM, indeksu fragmentu i flagi ostatniego fragmentu jako danych powiązanych. Przykładowy kod, który korzysta z interfejsu Drive API i jest zgodny z tą specyfikacją, znajdziesz w demonstracji open source.

Szyfrowanie i przesyłanie pliku

Aby przesłać plik CSE, aplikacja musi się uwierzytelnić, poprosić o token CSE, zaszyfrować lokalnie zawartość pliku, opakować klucz szyfrowania, a następnie przesłać zaszyfrowaną zawartość i metadane na Dysk Google.

Uzyskiwanie tokena szyfrowania po stronie klienta

Poproś o token CSE z Dysku Google, wywołując metodę Drive API Files:generateCseToken. Upewnij się, że w żądaniu nie ma parametru zapytania fileId. Aby utworzyć plik w określonym folderze, dodaj parametr zapytania parent z identyfikatorem folderu. Jeśli symbol parent zostanie pominięty, plik zostanie utworzony w głównym folderze Mojego dysku użytkownika. Odpowiedź zawiera unikalny identyfikator pliku przesłanego do Google oraz token autoryzacji JWT, który jest wymagany w kroku zawijania klucza.

Szyfrowanie danych lokalnie

  1. Użyj Google Tink, aby wygenerować unikalny klucz szyfrujący dane (DEK) dla pliku.
  2. Zaszyfruj zawartość pliku zgodnie ze strukturą zaszyfrowanego pliku.

Hasz klucza zasobu obliczeniowego

Aby obliczyć hash klucza zasobu:

  1. Wyodrębnij parametry resource_name i perimeter_id z otrzymanego od generateCseToken tokena autoryzacji jwt. Jeśli brakuje wartości perimeter_id, użyj pustego ciągu znaków.
  2. Oblicz HMAC-SHA256, używając jako klucza jawnego klucza DEK, a jako danych do podpisania ciągu znaków ResourceKeyDigest:my_resource_name:my_perimeter_id.
  3. Zakoduj wynikowy skrót w formacie Base64.

Więcej informacji znajdziesz w sekcji Hash klucza zasobu.

Obudowywanie klucza szyfrowania

Aby chronić klucz DEK, zaszyfruj go (zawiń) za pomocą zewnętrznej usługi KACLS.

  1. Wywołaj odpowiedni punkt końcowy:
  2. Przekaż tekst jawny klucza DEK, token uwierzytelniania dostawcy tożsamości, token autoryzacji Google (jeśli jest wymagany), resource_name z tokena JWT i reason.
  3. Otrzymanie zaszyfrowanego klucza DEK (WDEK) z KACLS.

Prześlij na Dysk

Użyj punktu końcowego Drive API files.create, aby wykonać standardowe przesyłanie pliku zaszyfrowanego obiektu blob. Ustaw te pola w metadanych pliku:

  • id: unikalny identyfikator pliku otrzymany w odpowiedzi generateCseToken.
  • mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
    • Parametr content można ustawić na typ MIME oryginalnego pliku.
  • clientEncryptionDetails:
    • encryptionState: "encrypted".
    • decryptionMetadata:
      • wrappedKey: Otrzymany z KACLS zaszyfrowany klucz DEK (WDEK).
      • kaclsId: identyfikator KACLS otrzymany w odpowiedzi generateCseToken.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • encryptionResourceKeyHash: skrót obliczony w sekcji Oblicz skrót klucza zasobu.

Przykład open source

Praktyczną demonstrację procesu szyfrowania i przesyłania znajdziesz w demonstracji open source. Zapewnia to działające rozwiązanie i może stanowić cenne źródło informacji.

Pobieranie i odszyfrowywanie pliku

Pobranie pliku CSE wymaga pobrania zaszyfrowanej zawartości i metadanych z Dysku Google, wysłania do usługi KACLS prośby o klucz DEK w postaci tekstu jawnego i odszyfrowania pliku lokalnie.

Pobieranie metadanych pliku i zaszyfrowanej zawartości

Wywołaj metodę interfejsu Drive API Files:get, aby pobrać metadane i zawartość pliku. clientEncryptionDetails zawiera DecryptionMetadata, który obejmuje opakowany klucz DEK (WDEK) i token JWT zawierający informacje o KACLS.

Rozpakowywanie klucza szyfrowania

  1. Wywołaj odpowiedni punkt końcowy:
  2. Przekaż WDEK, token uwierzytelniania dostawcy tożsamości, token autoryzacji Google (w razie potrzeby), resource_name i reason.
  3. Otrzymanie klucza DEK w formie tekstu jawnego z usługi KACLS.

lokalne odszyfrowywanie danych,

  1. Zainicjuj szyfr za pomocą tekstu jawnego DEK otrzymanego z KACLS.
  2. Pomiń początkowe magiczne bajty i odszyfruj pozostałą zawartość zgodnie z strukturą zaszyfrowanego pliku.

Przykład open source

Praktyczną demonstrację procesu pobierania i odszyfrowywania znajdziesz w wersji demonstracyjnej open source. Zapewnia to działające rozwiązanie i może stanowić cenne źródło informacji.

Sprawdzanie poprawności zaimportowanych plików

Google nie ma dostępu do kluczy szyfrowania, więc nie może odszyfrować ani zweryfikować Twoich plików po stronie serwera. Błędy implementacji podczas lokalnego szyfrowania lub zawijania klucza spowodują błędy podczas odszyfrowywania plików po stronie klienta. Zanim zaczniesz korzystać z własnej implementacji, musisz ją dokładnie sprawdzić.

Aby przesłane treści z szyfrowania po stronie klienta Google na Dysku Google działały prawidłowo, muszą być odpowiednio zaszyfrowane i zawierać prawidłowe metadane. Odpowiadasz za to, aby treści były prawidłowe i można było je odszyfrować.

Przeprowadzanie testów szyfrowania i odszyfrowywania w obie strony

Aby sprawdzić implementację, konieczne jest przetestowanie całego procesu. Obejmuje to pobranie zestawu plików testowych, zaszyfrowanie ich za pomocą logiki lokalnej, przesłanie ich na Dysk za pomocą interfejsu API, a następnie pobranie i odszyfrowanie. Po odszyfrowaniu porównaj wynikową treść z oryginalnymi plikami, aby upewnić się, że są identyczne. Ten proces pomaga wykryć wszelkie problemy z szyfrowaniem, zawijaniem kluczy lub obsługą metadanych. Demo open source pokazuje, jak możesz wdrożyć taki proces weryfikacji w swojej aplikacji.

Sprawdzanie wyrywkowe za pomocą Dysku Google

Sprawdź, czy przesłane pliki zawierają ikonę blokady w kliencie internetowym Dysku. Ręcznie pobierz niewielką liczbę przesłanych plików, aby sprawdzić, czy działają zgodnie z oczekiwaniami. To sprawdzenie korzysta z implementacji CSE Google, aby spróbować odszyfrować dane, co pomaga wyodrębnić problemy z szyfrowaniem lub logiką zawijania kluczy. Uwzględnij pliki z Mojego dysku i dysków współdzielonych.

Otwórz wersję demonstracyjną open source

Pakiet open source Drive CSE Upload zawiera kompletną, działającą bibliotekę Pythona i przykład wiersza poleceń, który implementuje przepływy przesyłania i pobierania CSE opisane w tym przewodniku. Zanim utworzysz własną integrację wyszukiwarki niestandardowej, zdecydowanie zalecamy sprawdzenie kodu demonstracyjnego.