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

Szyfrowanie po stronie klienta zapewnia, że dane są szyfrowane, zanim dotrą 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 usługi 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ć przydzielonym miejscem. 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ą podstawowego algorytmu 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 na koniec 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ę interfejsu 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 folderze głównym Mojego dysku użytkownika. Odpowiedź zawiera unikalny identyfikator pliku przesłanego pliku i 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ć skrót klucza zasobu:

  1. Wyodrębnij resource_name i perimeter_id z tokena autoryzacji jwt otrzymanego od generateCseToken. Jeśli brakuje wartości perimeter_id, użyj pustego ciągu znaków.
  2. Oblicz HMAC-SHA256, używając klucza DEK w postaci zwykłego tekstu i ciągu znaków ResourceKeyDigest:my_resource_name:my_perimeter_id jako danych do podpisania.
  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 (w razie potrzeby), resource_name z tokena JWT i reason.
  3. Otrzymaj opakowany klucz DEK (WDEK) z KACLS.

Prześlij na Dysk

Użyj punktu końcowego interfejsu Drive API files.create, aby przeprowadzić 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: Zawinięty klucz DEK (WDEK) otrzymany z KACLS.
      • kaclsId: identyfikator KACLS otrzymany w odpowiedzi generateCseToken.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • encryptionResourceKeyHash: skrót obliczony w sekcji Obliczanie skrótu 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 KACLS prośby o klucz DEK w postaci zwykłego tekstu 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 bajty magiczne 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ć i 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 wyszukiwarki niestandardowej 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ć wdrożenie, 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 na 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óre implementują opisane w tym przewodniku procesy przesyłania i pobierania w ramach szyfrowania po stronie klienta. Zanim utworzysz własną integrację wyszukiwarki niestandardowej, zdecydowanie zalecamy sprawdzenie kodu demonstracyjnego.