Clientseitig verschlüsselte Dateien mit der Drive API verwalten

Bei der clientseitigen Verschlüsselung werden Ihre Daten verschlüsselt, bevor sie die Drive-Server erreichen. So haben Sie die Kontrolle über Ihre Daten. In diesem Leitfaden wird beschrieben, wie Sie CSE-Dateien programmatisch mit der Drive API verschlüsseln und hochladen sowie herunterladen und entschlüsseln. Außerdem werden empfohlene Ansätze zum Testen und Validieren Ihrer Implementierung behandelt.

Hinweis

Bevor Sie verschlüsselte Dateien verwalten, richten Sie Ihre Google Workspace-Domain anhand der folgenden Checkliste ein:

Authentifizierung und Autorisierung

Für die Interaktion mit der Drive API und Ihrem KACLS müssen Sie eine Authentifizierungsmethode auswählen. Diese Wahl wirkt sich auf die Interaktion mit beiden Diensten aus:

  • Einzelperson: Wenn Sie sich als Einzelperson authentifizieren möchten, verwenden Sie den OAuth-Ablauf, um im Namen dieses Nutzers zu handeln. Verwenden Sie die Standard /wrap und /unwrap Endpunkte, und geben Sie das Google-Autorisierungstoken für diesen Nutzer an.
  • Administrator:Wenn Sie andere Nutzer in der Domain immitieren möchten, verwenden Sie ein Dienstkonto mit domainweiter Delegierung (DWD). Verwenden Sie die /privilegedwrap und /privilegedunwrap Endpunkte ohne Google-Autorisierungstoken.

Weitere Informationen zum Erstellen von Anmeldedaten finden Sie im Leitfaden Anmeldedaten für den Zugriff erstellen.

IdP-Authentifizierung für die Domain

Wenn Sie sich mit Ihrem IdP authentifizieren möchten, müssen Sie eine OAuth-Client-ID konfigurieren und die zugehörige Clientschlüsseldatei herunterladen. Ihre Anwendung muss ein Authentifizierungstoken von Ihrem IdP abrufen, um Anfragen an Ihren KACLS zu authentifizieren. Dieses Token ist erforderlich, damit Ihre Anwendung auf den Datenverschlüsselungsschlüssel zugreifen kann.

Sicherer Umgang mit Anmeldedaten

Ihre Anwendung verarbeitet vertrauliche Anmeldedaten für die Authentifizierung bei der Drive API und Ihrem IdP. Dazu gehören:

  • Vertrauliche Daten vom IdP, z. B. eine Clientschlüsseldatei
  • Vertrauliche Daten von Google, z. B. eine Datei mit dem privaten Schlüssel des Dienstkontos
  • Vertrauliche Daten, die von der App gespeichert werden, z. B. gespeicherte Anmeldedaten

Sie müssen dafür sorgen, dass alle diese Anmeldedaten sicher gespeichert werden.

Limits und Kontingente

Für clientseitig verschlüsselte Dateien gelten die Standardlimits und ‑kontingente von Drive. Beachten Sie die Limits für geteilte Ablagen, die allgemeinen Limits für Dateien und Ordner, und die Informationen zum Verwalten Ihres Kontingents. Außerdem muss Ihr Importtool Ratenlimits von Ihrem Key Access Control List Service (KACLS) und Ihrem Identitätsanbieter (IdP) verarbeiten.

Struktur verschlüsselter Dateien

Für Uploads und Downloads erwartet Drive das folgende clientseitig verschlüsselte Dateiformat.

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

Magic Header

Ein Magic Header (auch als Dateisignatur oder Magic Number bezeichnet) ist eine konstante Bytefolge, die ganz am Anfang einer Datei platziert wird, um ihr Format eindeutig zu identifizieren. Die Datei muss mit den Bytes 0x99 0x5E 0xCC 0x5E beginnen.

Verschlüsselte Chunks

Die Datei muss in 2-MiB-Chunks aufgeteilt werden. Jeder Chunk wird mit dem AEAD-Primitiv (Authenticated Encryption with Associated Data) der Google Tink-Bibliothek mit einem AES-GCM-Schlüsseltyp verschlüsselt. Dabei werden der Chunk-Index und ein Flag für den letzten Chunk als zugehörige Daten verwendet. Ein Code beispiel, das die Drive API verwendet und dieser Spezifikation entspricht, finden Sie in der Open-Source-Demo.

Datei verschlüsseln und hochladen

Wenn Sie eine CSE-Datei hochladen möchten, muss sich Ihre Anwendung authentifizieren, ein CSE-Token anfordern, den Dateiinhalt lokal verschlüsseln, den Verschlüsselungsschlüssel verpacken und schließlich den verschlüsselten Inhalt und die Metadaten in Google Drive hochladen.

CSE-Token abrufen

Fordern Sie ein CSE-Token von Google Drive an, indem Sie die Drive API Files:generateCseToken Methode aufrufen. Achten Sie darauf, dass Sie den Abfrageparameter fileId nicht in die Anfrage einfügen. Wenn Sie die Datei in einem bestimmten Ordner erstellen möchten, fügen Sie den Abfrageparameter parent mit der Ordner-ID ein. Wenn parent nicht angegeben wird, wird die Datei im Stammordner „Meine Ablage“ des Nutzers erstellt. Die Antwort enthält eine eindeutige Datei-ID für den Upload und ein JWT-Autorisierungstoken, das für den Schritt zum Verpacken des Schlüssels erforderlich ist.

Daten lokal verschlüsseln

  1. Verwenden Sie Google Tink, um einen eindeutigen Datenverschlüsselungsschlüssel (Data Encryption Key, DEK) für die Datei zu generieren.
  2. Verschlüsseln Sie den Dateiinhalt gemäß der Struktur der verschlüsselten Datei.

Hash des Ressourcenschlüssels berechnen

So berechnen Sie den Hash des Ressourcenschlüssels:

  1. Extrahieren Sie resource_name und perimeter_id aus dem jwt-Autorisierungstoken, das Sie von generateCseToken erhalten haben. Wenn perimeter_id fehlt, verwenden Sie einen leeren String.
  2. Berechnen Sie HMAC-SHA256 mit dem DEK im Klartext als Schlüssel und dem String ResourceKeyDigest:my_resource_name:my_perimeter_id als zu signierende Daten.
  3. Codieren Sie den resultierenden Hash mit Base64.

Weitere Informationen finden Sie unter Ressourcenschlüssel Hash.

Verschlüsselungsschlüssel verpacken

Zum Schutz des DEK verschlüsseln (verpacken) Sie ihn mit Ihrem externen KACLS.

  1. Rufen Sie den entsprechenden Endpunkt auf:
  2. Übergeben Sie den DEK im Klartext, Ihr IdP-Authentifizierungstoken, das Google-Autorisierungstoken (falls erforderlich), den resource_name aus dem JWT und einen reason.
  3. Sie erhalten den verpackten DEK (Wrapped DEK, WDEK) vom KACLS.

In Drive hochladen

Verwenden Sie den Drive API files.create Endpunkt, um einen Standard-Datei-Upload des verschlüsselten Dateiblobs durchzuführen. Legen Sie in den Dateimetadaten die folgenden Felder fest:

  • id: Die eindeutige Datei-ID, die Sie in der Antwort von generateCseToken erhalten haben.
  • mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
    • Der Parameter content kann auf den MIME-Typ der Originaldatei festgelegt werden.
  • clientEncryptionDetails:
    • encryptionState: "encrypted".
    • decryptionMetadata:
      • wrappedKey: Der verpackte DEK (WDEK), den Sie vom KACLS erhalten haben.
      • kaclsId: Die KACLS-ID, die Sie in der Antwort von generateCseToken erhalten haben.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • encryptionResourceKeyHash: Der Hash, der unter Hash des Ressourcenschlüssels berechnen berechnet wurde.

Open-Source-Beispiel

Eine praktische Demonstration des Verschlüsselungs- und Uploadvorgangs finden Sie in der Open-Source-Demo. Diese bietet eine funktionierende Lösung und kann als wertvolle Referenz dienen.

Datei herunterladen und entschlüsseln

Zum Herunterladen einer CSE-Datei müssen Sie den verschlüsselten Inhalt und die Metadaten aus Google Drive abrufen, den DEK im Klartext von Ihrem KACLS anfordern und die Datei lokal entschlüsseln.

Dateimetadaten und verschlüsselten Inhalt abrufen

Rufen Sie die Drive API Files:get-Methode auf, um die Metadaten und den Inhalt der Datei abzurufen. clientEncryptionDetails enthält DecryptionMetadata, einschließlich des verpackten DEK (WDEK) und des JWT mit den KACLS-Informationen.

Verschlüsselungsschlüssel entpacken

  1. Rufen Sie den entsprechenden Endpunkt auf:
  2. Übergeben Sie den WDEK, Ihr IdP-Authentifizierungstoken, das Google-Autorisierungstoken (falls erforderlich), den resource_name und einen reason.
  3. Sie erhalten den DEK im Klartext vom KACLS.

Daten lokal entschlüsseln

  1. Initialisieren Sie die Verschlüsselung mit dem DEK im Klartext, den Sie vom KACLS erhalten haben.
  2. Überspringen Sie die ersten Magic Bytes und entschlüsseln Sie den restlichen Inhalt gemäß der Struktur der verschlüsselten Datei.

Open-Source-Beispiel

Eine praktische Demonstration des Download- und Entschlüsselungsvorgangs finden Sie in der Open-Source-Demo. Diese bietet eine funktionierende Lösung und kann als wertvolle Referenz dienen.

Importierte Dateien validieren

Da Google keinen Zugriff auf die Verschlüsselungsschlüssel hat, kann Google Ihre Dateien nicht serverseitig entschlüsseln und validieren. Implementierungsfehler während der lokalen Verschlüsselung oder der Schlüsselverpackung führen zu Fehlern beim clientseitigen Entschlüsseln von Dateien. Eine gründliche Validierung ist unerlässlich, bevor Sie Ihre eigene Implementierung verwenden.

Damit hochgeladene Google Drive-CSE-Inhalte ordnungsgemäß funktionieren, müssen sie korrekt verschlüsselt sein und die richtigen Metadaten enthalten. Sie sind dafür verantwortlich, dass der Inhalt gültig ist und entschlüsselt werden kann.

Tests zur Roundtrip-Verschlüsselung und ‑Entschlüsselung durchführen

Um Ihre Implementierung zu validieren, ist es wichtig, den End-to-End-Ablauf zu testen. Dazu müssen Sie eine Reihe von Testdateien verwenden, sie mit Ihrer lokalen Logik verschlüsseln, mit der API in Drive hochladen und dann herunterladen und entschlüsseln. Vergleichen Sie nach der Entschlüsselung den resultierenden Inhalt mit den Originaldateien, um sicherzustellen, dass sie identisch sind. So lassen sich Probleme bei der Verschlüsselung, der Schlüsselverpackung oder der Metadatenverarbeitung erkennen. In der Open-Source Demo wird gezeigt, wie Sie einen solchen Validierungs prozess in Ihrer eigenen Anwendung implementieren können.

Stichproben mit Google Drive

Prüfen Sie, ob die hochgeladenen Dateien im Drive-Webclient ein Schlosssymbol enthalten. Laden Sie eine kleine Anzahl hochgeladener Dateien manuell herunter, um zu prüfen, ob sie wie erwartet funktionieren. Bei dieser Prüfung wird die CSE-Implementierung von Google verwendet, um die Entschlüsselung zu versuchen. So lassen sich Probleme in Ihrer Verschlüsselungs- oder Schlüsselverpackungslogik isolieren. Fügen Sie Dateien aus Meine Ablage und Geteilte Ablagen ein.

Open-Source-Demo

Das Open-Source-Paket Drive CSE Upload bietet eine vollständige, funktionierende Python-Bibliothek und ein Befehlszeilenbeispiel, das die in diesem Leitfaden beschriebenen CSE-Upload- und ‑Downloadabläufe implementiert. Wir empfehlen dringend, den Democode zu prüfen, bevor Sie Ihre eigene CSE-Integration erstellen.