Encrypt & decrypt data

This guide describes how encryption and decryption works using the Google Workspace Client-side Encryption API.

You must allowlist any Identity Provider (IdP) services used by users sharing encrypted files. You can usually find the required IdP details in their publicly-available .well-known file; otherwise, contact the organization's Google Workspace administrator for their IdP details.

Encrypt data

When a Google Workspace user requests to save or store client-side encrypted (CSE) data, Google Workspace sends a wrap request to your KACLS endpoint URL for encryption. In addition to optional security checks, such as perimeter and JWT claim-based checks, your KACLS must perform the following steps:

1. Validate the requesting user.

   • Validate both the authentication token and authorization token.
   • Check that authorization and authentication tokens are for the same user by doing a case-insensitive match on the email claims.
   • When the authentication token contains the optional google_email claim, it must be compared against the email claim in the authorization token using a case-insensitive approach. Don't use the email claim within the authentication token for this comparison.
   • In scenarios where the authentication token lacks the optional google_email claim, the email claim within the authentication token should be compared with the email claim in the authorization token, using a case-insensitive method.
   • In scenarios where Google issues an authorization token for an email not associated with a Google Account, the email_type claim must be present. This forms a crucial part of the Guest Access feature, providing valuable information for KACLS to enforce additional security measures on external users.
     • Some examples of how a KACLS can use this information include:
     • To impose additional logging requirements.
     • To restrict the authentication token issuer to a dedicated Guest IdP.
     • To require additional claims on the authentication token.
     • If a customer has not configured Guest Access, then all requests where email_type is set to google-visitor or customer-idp can be rejected. Requests with an email_type of google or with an unset email_type should continue to be accepted.
   • Check that the role claim in the authorization token is "writer" or "upgrader".
   • Check that the kacls_url claim in the authorization token matches the current KACLS URL. This check allows detection of potential man-in-the-middle servers configured by insiders or rogue domain administrators.
   • Perform a perimeter check using both authentication and authorization claims.

2. Encrypt the following parts using an authenticated encryption algorithm:

   • Data Encryption Key (DEK)
   • The resource_name and perimeter_id values from the authorization token
   • Any additional sensitive data

3. Log the operation, including the user originating it, the resource_name and the reason passed in the request.

4. Return an opaque binary object to be stored by Google Workspace alongside the encrypted object and sent as-is in any subsequent key unwrapping operation. Or, serve a structured error reply.

   • The binary object should contain the only copy of the encrypted DEK, implementation specific data can be stored in it.

Note: Do not store the DEK in your KACLS system. Instead, encrypt it and return it in the wrapped_key object to prevent discrepancies for the lifetime of the file. Google doesn't send deletion requests to the KACLS when objects are deleted.

Decrypt data

When a Google Workspace user requests to open client-side encrypted (CSE) data, Google Workspace sends an unwrap request to your KACLS endpoint URL for decryption. In addition to optional security checks, such as perimeter and JWT claim-based checks, your KACLS must perform the following steps:

1. Validate the requesting user.

   • Validate both the authentication token and authorization token.
   • Check that authorization and authentication tokens are for the same user by doing a case-insensitive match on the email claims.
   • When the authentication token contains the optional google_email claim, it must be compared against the email claim in the authorization token using a case-insensitive approach. Don't use the email claim within the authentication token for this comparison.
   • In scenarios where the authentication token lacks the optional google_email claim, the email claim within the authentication token should be compared with the email claim in the authorization token, using a case-insensitive method.
   • In scenarios where Google issues an authorization token for an email not associated with a Google Account, the email_type claim must be present. This forms a crucial part of the Guest Access feature, providing valuable information for KACLS to enforce additional security measures on external users.
     • Some examples of how a KACLS can use this information include:
     • To impose additional logging requirements.
     • To restrict the authentication token issuer to a dedicated Guest IdP.
     • To require additional claims on the authentication token.
     • If a customer has not configured Guest Access, then all requests where email_type is set to google-visitor or customer-idp can be rejected. Requests with an email_type of google or with an unset email_type should continue to be accepted.
   • Check that the role claim in the authorization token is "reader" or "writer".
   • Check that the kacls_url claim in the authorization token matches the current KACLS URL. This allows detection of potential man-in-the-middle servers configured by insiders or rogue domain administrators.

2. Decrypt the following parts using an authenticated encryption algorithm:

   • Data Encryption Key (DEK)
   • The resource_name and perimeter_id values from the authorization token
   • Any additional sensitive data

3. Check that the resource_name in the authorization token and decrypted blob match.

4. Perform a perimeter check using both authentication and authorization claims.

5. Log the operation, including the user originating it, the resource_name and the reason passed in the request.

6. Return the unwrapped DEK or a structured error reply.

Note: To decrypt Google Takeout requests, see takeout_unwrap.