Cripta e decripta i dati

Questa guida descrive il funzionamento della crittografia e della decrittografia con l'API Crittografia lato client di Google Workspace.

Devi inserire nella lista consentita tutti i servizi di provider di identità (IdP) utilizzati dagli utenti che condividono file criptati. Di solito puoi trovare i dettagli dell'IdP richiesti nel file .well-known disponibile pubblicamente. In caso contrario, contatta l'amministratore di Google Workspace dell'organizzazione per richiedere i dettagli dell'IdP.

Criptare i dati

Quando un utente di Google Workspace richiede di salvare o archiviare dati con crittografia lato client (CSE), Google Workspace invia una richiesta wrap al tuo URL endpoint KACLS per la crittografia. Oltre ai controlli di sicurezza facoltativi, come i controlli basati su claim JWT e sul perimetro, i KACLS devono eseguire i seguenti passaggi:

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

    • Convalida sia il token di autenticazione sia il token di autorizzazione.
    • Verifica che i token di autorizzazione e autenticazione siano per lo stesso utente eseguendo una corrispondenza senza distinzione tra maiuscole e minuscole sui claim email.
    • Quando il token di autenticazione contiene l'affermazione facoltativa google_email, deve essere confrontato con l'affermazione email nel token di autorizzazione utilizzando un approccio insensibile alle maiuscole. Per questo confronto, non utilizzare la rivendicazione email all'interno del token di autenticazione.
    • Negli scenari in cui il token di autenticazione non contiene il claim facoltativogoogle_email, il claim email all'interno del token di autenticazione deve essere confrontato con il claim email nel token di autorizzazione utilizzando un metodo che non è sensibile alle maiuscole.
    • Negli scenari in cui Google emette un token di autorizzazione per un'email non associata a un Account Google, il reclamo email_type deve essere presente. Questa è una parte fondamentale della funzionalità Accesso ospite, in quanto fornisce informazioni preziose per gli elenchi KACL per applicare misure di sicurezza aggiuntive agli utenti esterni.
      • Di seguito sono riportati alcuni esempi di come un KACLS può utilizzare queste informazioni:
      • Per imporre requisiti di logging aggiuntivi.
      • Per limitare l'emittente del token di autenticazione a un IdP ospite dedicato.
      • Per richiedere altri claim sul token di autenticazione.
      • Se un cliente non ha configurato l'accesso ospite, tutte le richieste in cui email_type è impostato su google-visitor o customer-idp possono essere rifiutate. Le richieste con un valore email_type pari a google o con un valore email_type non impostato dovrebbero continuare a essere accettate.
    • Verifica che l'affermazione role nel token di autorizzazione sia "writer" o "upgrader".
    • Verifica che l'affermazione kacls_url nel token di autorizzazione corrisponda all'URL KACLS corrente. Questo controllo consente di rilevare potenziali server man-in-the-middle configurati da addetti ai lavori o amministratori di dominio malintenzionati.
    • Esegui un controllo del perimetro utilizzando sia le rivendicazioni di autenticazione che quelle di autorizzazione.

  2. Crittografa le seguenti parti utilizzando un algoritmo di crittografia autenticata:

    • 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, incluso l'utente che l'ha generata, il resource_name e il motivo passato nella richiesta.

  4. Restituisce un oggetto binario opaco da memorizzare da parte di Google Workspace insieme all'oggetto criptato e da inviare così com'è in qualsiasi operazione di sblocco della chiave successiva. In alternativa, puoi fornire una risposta di errore strutturata.

    • L'oggetto binario deve contenere l'unica copia della DEK criptata, ma al suo interno possono essere memorizzati dati specifici dell'implementazione.

Decriptare i dati

Quando un utente di Google Workspace richiede di aprire dati con crittografia lato client (CSE), Google Workspace invia una richiesta unwrap all'URL dell'endpoint KACLS per la decrittografia. Oltre ai controlli di sicurezza facoltativi, come i controlli basati su claim JWT e sul perimetro, i KACLS devono eseguire i seguenti passaggi:

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

    • Convalida sia il token di autenticazione sia il token di autorizzazione.
    • Verifica che i token di autorizzazione e autenticazione siano per lo stesso utente eseguendo una corrispondenza senza distinzione tra maiuscole e minuscole sui claim email.
    • Quando il token di autenticazione contiene l'affermazione facoltativa google_email, deve essere confrontato con l'affermazione email nel token di autorizzazione utilizzando un approccio insensibile alle maiuscole. Per questo confronto, non utilizzare la rivendicazione email all'interno del token di autenticazione.
    • Negli scenari in cui il token di autenticazione non contiene il claim facoltativogoogle_email, il claim email all'interno del token di autenticazione deve essere confrontato con il claim email nel token di autorizzazione utilizzando un metodo che non è sensibile alle maiuscole.
    • Negli scenari in cui Google emette un token di autorizzazione per un'email non associata a un Account Google, il reclamo email_type deve essere presente. Questa è una parte fondamentale della funzionalità Accesso ospite, in quanto fornisce informazioni preziose per gli elenchi KACL per applicare misure di sicurezza aggiuntive agli utenti esterni.
      • Di seguito sono riportati alcuni esempi di come un KACLS può utilizzare queste informazioni:
      • Per imporre requisiti di logging aggiuntivi.
      • Per limitare l'emittente del token di autenticazione a un IdP ospite dedicato.
      • Per richiedere altri claim sul token di autenticazione.
      • Se un cliente non ha configurato l'accesso ospite, tutte le richieste in cui email_type è impostato su google-visitor o customer-idp possono essere rifiutate. Le richieste con un valore email_type pari a google o con un valore email_type non impostato dovrebbero continuare a essere accettate.
    • Verifica che l'affermazione role nel token di autorizzazione sia "reader" o "writer".
    • Verifica che l'affermazione kacls_url nel token di autorizzazione corrisponda all'URL KACLS corrente. In questo modo è possibile rilevare potenziali server man-in-the-middle configurati da addetti ai lavori o amministratori di dominio malintenzionati.

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

    • 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 valore resource_name nel token di autorizzazione e nel blob decriptato sia uguale.

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

  5. Registra l'operazione, incluso l'utente che l'ha generata, il resource_name e il motivo passato nella richiesta.

  6. Restituire la DEK decriptata o una risposta di errore strutturata.