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.
   • 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.
   • 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.