Cripta e decripta i dati

Questa guida descrive il funzionamento della crittografia e della decriptazione con l'API Client-Side Encryption di Google Workspace.

Devi inserire nella lista consentita tutti i servizi del provider di identità (IdP) utilizzati dagli utenti che condividono file criptati. Generalmente, i dettagli dell'IdP richiesti sono disponibili nel file .well-known disponibile pubblicamente. In alternativa, contatta l'amministratore di Google Workspace dell'organizzazione per conoscere i dettagli dell'IdP.

Cripta i dati

Quando un utente di Google Workspace richiede di salvare o archiviare i dati con crittografia lato client, Google Workspace invia una richiesta wrap all'URL dell'endpoint KACLS per la crittografia. Oltre ai controlli di sicurezza facoltativi, come i controlli del perimetro e delle dichiarazioni JWT, il KACLS deve eseguire i seguenti passaggi:

1. Convalida l'utente che ha inviato la richiesta.

   • Convalida il token di autenticazione e il token di autorizzazione.
   • Verifica che i token di autorizzazione e di autenticazione siano per lo stesso utente eseguendo una corrispondenza senza distinzione tra maiuscole e minuscole nelle attestazioni email.
   • Se il token di autenticazione contiene l'attestazione google_email facoltativa, deve essere confrontata con l'attestazione email nel token di autorizzazione utilizzando un approccio senza distinzione tra maiuscole e minuscole. Non utilizzare l'attestazione email all'interno del token di autenticazione per questo confronto.
   • Negli scenari in cui il token di autenticazione non dispone dell'attestazione google_email facoltativa, l'attestazione email all'interno del token di autenticazione deve essere confrontata con l'attestazione email nel token di autorizzazione, utilizzando un metodo che non fa distinzione tra maiuscole e minuscole.
   • Negli scenari in cui Google emette un token di autorizzazione per un'email non associata a un Account Google, è necessario presentare la rivendicazione email_type. Questo è una parte fondamentale della funzionalità Accesso come ospite, in quanto fornisce informazioni preziose affinché KACLS possa applicare ulteriori misure di sicurezza agli utenti esterni.
     • Ecco alcuni esempi di come un KACLS può usare queste informazioni:
     • Per imporre ulteriori requisiti di logging.
     • a limitare l'emittente del token di autenticazione a un IdP guest dedicato.
     • Per richiedere ulteriori attestazioni sul token di autenticazione.
     • Se un cliente non ha configurato l'accesso come ospite, tutte le richieste in cui email_type è impostato su google-visitor o customer-idp possono essere rifiutate. Le richieste con valore email_type pari a google o con valore email_type non impostato dovrebbero continuare a essere accettate.
   • Verifica che l'attestazione role nel token di autorizzazione sia "writer" o "upgrader".
   • Verifica che l'attestazione kacls_url nel token di autorizzazione corrisponda all'URL KACLS corrente. Questo controllo consente di rilevare potenziali server man in the middle configurati da utenti malintenzionati interni o amministratori di dominio non autorizzati.
   • Esegui un controllo del perimetro utilizzando sia le richieste di autenticazione che quelle di autorizzazione.

2. Cripta le seguenti parti utilizzando un algoritmo di crittografia autenticato:

   • Chiave di crittografia dei dati (DEK)
   • I valori resource_name e perimeter_id del token di autorizzazione
   • Eventuali altri dati sensibili

3. Registra l'operazione, inclusi l'utente che l'ha originata, l'resource_name e il motivo trasmesso nella richiesta.

4. Restituisci un oggetto binario opaco che deve essere archiviato da Google Workspace insieme all'oggetto criptato e inviato così com'è in ogni successiva operazione di unwrapping della chiave. In alternativa, puoi visualizzare una risposta di errore strutturata.

   • L'oggetto binario deve contenere l'unica copia della DEK criptata; i dati specifici dell'implementazione possono essere archiviati al suo interno.

Nota: non memorizzare la DEK nel sistema KACLS. Piuttosto, criptalo e restituiscilo nell'oggetto wrapped_key per evitare discrepanze per la durata del file. Google non invia richieste di eliminazione al KACLS quando gli oggetti vengono eliminati.

Decripta i dati

Quando un utente di Google Workspace richiede di aprire i dati con crittografia lato client, Google Workspace invia una richiesta unwrap all'URL dell'endpoint KACLS per la decrittografia. Oltre ai controlli di sicurezza facoltativi, ad esempio ai controlli del perimetro e delle dichiarazioni JWT, il KACLS deve eseguire i seguenti passaggi:

1. Convalida l'utente che ha inviato la richiesta.

   • Convalida il token di autenticazione e il token di autorizzazione.
   • Verifica che i token di autorizzazione e di autenticazione siano per lo stesso utente eseguendo una corrispondenza senza distinzione tra maiuscole e minuscole nelle attestazioni email.
   • Se il token di autenticazione contiene l'attestazione google_email facoltativa, deve essere confrontata con l'attestazione email nel token di autorizzazione utilizzando un approccio senza distinzione tra maiuscole e minuscole. Non utilizzare l'attestazione email all'interno del token di autenticazione per questo confronto.
   • Negli scenari in cui il token di autenticazione non dispone dell'attestazione google_email facoltativa, l'attestazione email all'interno del token di autenticazione deve essere confrontata con l'attestazione email nel token di autorizzazione, utilizzando un metodo che non fa distinzione tra maiuscole e minuscole.
   • Negli scenari in cui Google emette un token di autorizzazione per un'email non associata a un Account Google, è necessario presentare la rivendicazione email_type. Questo è una parte fondamentale della funzionalità Accesso come ospite, in quanto fornisce informazioni preziose affinché KACLS possa applicare ulteriori misure di sicurezza agli utenti esterni.
     • Ecco alcuni esempi di come un KACLS può usare queste informazioni:
     • Per imporre ulteriori requisiti di logging.
     • a limitare l'emittente del token di autenticazione a un IdP guest dedicato.
     • Per richiedere ulteriori attestazioni sul token di autenticazione.
     • Se un cliente non ha configurato l'accesso come ospite, tutte le richieste in cui email_type è impostato su google-visitor o customer-idp possono essere rifiutate. Le richieste con valore email_type pari a google o con valore email_type non impostato dovrebbero continuare a essere accettate.
   • Verifica che l'attestazione role nel token di autorizzazione sia "lettore" o "autore".
   • Verifica che l'attestazione kacls_url nel token di autorizzazione corrisponda all'URL KACLS corrente. Ciò consente il rilevamento di potenziali server man-in-the-middle configurati da utenti malintenzionati interni o amministratori di dominio non autorizzati.

2. Decripta le seguenti parti utilizzando un algoritmo di crittografia autenticato:

   • Chiave di crittografia dei dati (DEK)
   • I valori resource_name e perimeter_id del token di autorizzazione
   • Eventuali altri dati sensibili

3. Verifica che il resource_name nel token di autorizzazione e nel blob decriptato corrispondano.

4. Esegui un controllo del perimetro utilizzando sia le attestazioni di autenticazione che quelle di autorizzazione.

5. Registra l'operazione, inclusi l'utente che l'ha originata, l'resource_name e il motivo trasmesso nella richiesta.

6. Restituisce la DEK senza wrapping o una risposta a un errore strutturato.

Nota: per decriptare le richieste di Google Takeout visita la pagina takeout_unwrap.