Gestire i file con crittografia lato client con l'API Drive

La crittografia lato client (CSE) garantisce che i dati vengano criptati prima di raggiungere i server di Drive, consentendoti di controllarli. Questa guida descrive la procedura di criptaggio e caricamento, nonché di download e decriptaggio, dei file con crittografia lato client a livello di programmazione utilizzando l'API Drive. Inoltre, vengono trattati gli approcci consigliati per testare e convalidare l'implementazione.

Prima di iniziare

Prima di gestire i file criptati, configura il tuo dominio Google Workspace utilizzando il seguente elenco di controllo:

Autenticazione e autorizzazione

Per interagire con l'API Drive e i tuoi KACL, devi scegliere un metodo di autenticazione. Questa scelta influisce sul modo in cui interagisci con entrambi i servizi:

Per ulteriori dettagli sulla creazione delle credenziali, consulta la guida Creare le credenziali di accesso.

Autenticazione IdP del dominio

Per l'autenticazione con il tuo IdP, devi configurare un ID client OAuth e scaricare il relativo file client secret. La tua applicazione deve ottenere un token di autenticazione dal tuo IdP per autenticare le richieste al tuo KACLS. Questo token è necessario per consentire alla tua applicazione di accedere alla chiave di crittografia dei dati.

Gestire le credenziali in modo sicuro

La tua applicazione gestisce le credenziali sensibili per l'autenticazione nell'API Drive e nel tuo IdP. tra cui:

  • Materiale segreto dell'IdP, ad esempio un file client secret
  • Materiale segreto di Google, ad esempio un file di chiave privata del service account
  • Materiale segreto memorizzato dall'app, ad esempio le credenziali salvate

Devi assicurarti che tutte queste credenziali siano archiviate in modo sicuro.

Limiti e quote

I file con crittografia lato client sono soggetti ai limiti e alle quote standard di Drive. Tieni presente i limiti dei Drive condivisi, i limiti generali di file e cartelle e come gestire la tua quota. Inoltre, lo strumento di importazione deve gestire i limiti di frequenza del servizio di controllo dell'accesso per le chiavi (KACLS) e del provider di identità (IdP).

Struttura del file criptato

Drive prevede il seguente formato di file con crittografia lato client per caricamenti e download.

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

Intestazione magica

Un'intestazione magica (nota anche come firma del file o numero magico) è una sequenza di byte costante posizionata all'inizio di un file per identificarne in modo univoco il formato. Il file deve iniziare con i byte 0x99 0x5E 0xCC 0x5E.

Chunk criptati

Il file deve essere suddiviso in blocchi da 2 MiB. Ogni blocco viene criptato utilizzando la primitiva di crittografia autenticata con dati associati (AEAD) della libreria Google Tink con un tipo di chiave AES-GCM, utilizzando l'indice del blocco e un flag di blocco finale come dati associati. Per un esempio di codice che utilizza l'API Drive ed è conforme a questa specifica, consulta la demo open source.

Criptare e caricare un file

Per caricare un file CSE, l'applicazione deve autenticarsi, richiedere un token CSE, criptare localmente i contenuti del file, eseguire il wrapping della chiave di crittografia e infine caricare i contenuti criptati e i metadati su Google Drive.

Ottenere un token CSE

Richiedi un token CSE da Google Drive chiamando il metodo Files:generateCseToken dell'API Drive. Assicurati di non includere il parametro di query fileId nella richiesta. Per creare il file in una cartella specifica, includi il parametro di query parent con l'ID cartella. Se parent viene omesso, il file viene creato nella cartella principale Il mio Drive dell'utente. La risposta include un ID file univoco per il caricamento e un token di autorizzazione JWT, necessario per il passaggio del wrapping della chiave.

Criptare i dati localmente

  1. Utilizza Google Tink per generare una chiave di crittografia dei dati (DEK) univoca per il file.
  2. Cripta i contenuti del file in base alla struttura del file criptato.

Compute Resource Key Hash

Per calcolare l'hash della chiave della risorsa:

  1. Estrai resource_name e perimeter_id dal token di autorizzazione jwt ricevuto da generateCseToken. Se perimeter_id non è presente, utilizza una stringa vuota.
  2. Calcola HMAC-SHA256 utilizzando la chiave DEK in testo non crittografato come chiave e la stringa ResourceKeyDigest:my_resource_name:my_perimeter_id come dati da firmare.
  3. Codifica in base64 l'hash risultante.

Per maggiori dettagli, consulta Hash della chiave della risorsa.

Eseguire il wrapping della chiave di crittografia

Per proteggere la DEK, criptala (esegui il wrapping) utilizzando i tuoi KACL esterni.

  1. Chiama l'endpoint appropriato:
  2. Trasmetti la DEK in testo non crittografato, il token di autenticazione IdP, il token di autorizzazione Google (se necessario), il resource_name del JWT e un reason.
  3. Ricevi la WDEK (Wrapped DEK) dal KACLS.

Carica su Drive

Utilizza l'endpoint files.create dell'API Drive per eseguire un caricamento di file standard del blob del file criptato. Imposta i seguenti campi nei metadati del file:

  • id: l'ID univoco del file ricevuto dalla risposta generateCseToken.
  • mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
    • Il parametro content può essere impostato sul tipo MIME del file originale.
  • clientEncryptionDetails:
    • encryptionState: "encrypted".
    • decryptionMetadata:
      • wrappedKey: La DEK sottoposta a wrapping (WDEK) ricevuta dal KACLS.
      • kaclsId: l'ID KACLS ricevuto dalla risposta generateCseToken.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • encryptionResourceKeyHash: l'hash calcolato in Compute Resource Key Hash.

Esempio di open source

Per una dimostrazione pratica della procedura di crittografia e caricamento, consulta la demo open source. Ciò fornisce una soluzione funzionante e può servire da riferimento prezioso.

Scaricare e decriptare un file

Il download di un file CSE richiede il recupero dei contenuti e dei metadati criptati da Google Drive, la richiesta della DEK in testo non crittografato dal tuo KACLS e la decrittografia del file in locale.

Recuperare i metadati dei file e i contenuti criptati

Chiama il metodo dell'API Drive Files:get per recuperare i metadati e i contenuti del file. clientEncryptionDetails contiene DecryptionMetadata, che include la DEK sottoposta a wrapping (WDEK) e il JWT contenente le informazioni KACLS.

Estrarre la chiave di crittografia

  1. Chiama l'endpoint appropriato:
  2. Trasmetti la WDEK, il token di autenticazione IdP, il token di autorizzazione Google (se necessario), resource_name e reason.
  3. Ricevi la DEK in testo non crittografato dal KACLS.

Decrittografare i dati localmente

  1. Inizializza la crittografia utilizzando la DEK in testo non crittografato ricevuta da KACLS.
  2. Salta i byte magici iniziali e decripta i contenuti rimanenti in base alla struttura del file criptato.

Esempio di open source

Per una dimostrazione pratica della procedura di download e decrittografia, consulta la demo open source. Ciò fornisce una soluzione funzionante e può servire da riferimento prezioso.

Convalidare i file importati

Poiché Google non ha accesso alle chiavi di crittografia, non può decriptare e convalidare i tuoi file lato server. Gli errori di implementazione durante le fasi di crittografia locale o wrapping della chiave comporteranno errori durante la decriptografia lato client dei file. Una convalida accurata è fondamentale prima di utilizzare la tua implementazione.

Affinché i contenuti di Google Drive con crittografia lato client caricati funzionino correttamente, devono essere crittografati correttamente e contenere i metadati corretti. Sei responsabile di garantire che i contenuti siano validi e possano essere decriptati.

Esegui test di crittografia e decrittografia andata e ritorno

Per convalidare l'implementazione, è fondamentale testare il flusso end-to-end. Ciò comporta l'acquisizione di un insieme di file di test, la loro crittografia utilizzando la logica locale, il loro caricamento su Drive utilizzando l'API e il loro download e decrittografia. Dopo la decriptografia, confronta i contenuti risultanti con i file originali per assicurarti che siano identici. Questa procedura consente di rilevare eventuali problemi nella crittografia, nel wrapping delle chiavi o nella gestione dei metadati. La demo open source mostra come implementare un processo di convalida di questo tipo all'interno della tua applicazione.

Controllo a campione con Google Drive

Verifica che i file caricati includano un'icona a forma di lucchetto nel client web di Drive. Scarica manualmente un numero ridotto di file caricati per verificare che funzionino come previsto. Questo controllo utilizza l'implementazione CSE di Google per tentare la decriptazione, contribuendo a isolare i problemi nella logica di crittografia o wrapping delle chiavi. Includi i file sia da Il mio Drive che dai Drive condivisi.

Demo open source

Il pacchetto open source Drive CSE Upload fornisce una libreria Python completa e funzionante e un esempio di riga di comando che implementa i flussi di caricamento e download di CSE descritti in questa guida. Ti consigliamo vivamente di esaminare il codice demo prima di creare la tua integrazione del motore di ricerca personalizzato.