The Google Workspace Client-side Encryption API is currently in Restricted Beta. Apply for access

Encrypt & decrypt data

Stay organized with collections Save and categorize content based on your preferences.

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

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.

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.