If your organization uses Google Workspace Client-side encryption (CSE), you can use the decrypter utility to decrypt client-side encrypted files and email messages that you export using the Data Export tool or Google Vault . You can run the decrypter from a command line.
When you run the decrypter, you'll use command-line flags to specify your identity provider (IdP) authentication information, the location of encrypted files, the output location for decrypted files, and other options. You can also create a configuration (config) file to save decrypter flags you frequently use.
Before you begin
- When you decrypt a Google Docs, Sheets, or Slides file, the file name ends with
.gdoczipor similar. After decryption, you can convert these files to Microsoft Office format using the file converter tool. For details, go to Convert exported and decrypted Google files to Microsoft Office files . - If you export Gmail CSE messages from Google Vault, you need to export in the MBOX format. The decrypter can’t process exports in the PST format.
- The decrypter utility can decrypt any messages encrypted with S/MIME certificates. It can also decrypt messages encrypted without S/MIME certificates (that is, messages using Gmail end-to-end encryption (E2EE) ), if your users encrypted the messages or the original message in threads.
- The decrypter utility can'tdecrypt messages (including all messages in a thread) encrypted without S/MIME certificates (Gmail E2EE) at another organization.
System requirements
- Microsoft Windows version 10 or 11 64-bit
- macOS 12 (Monterey) or later. Both Apple and Intel processors are supported.
- Linux x86_64.
Download the decrypter
Open the archive or volume and extract the decrypter executable to a local directory or folder.
Configure key service access
The decrypter sends queries to your encryption key service, also called a key access control list service (KACLS), which protects each encrypted file or message in your export. Ask your identity provider's (IdP's) administrator and your encryption key service administrator for credentials the KACLS will accept; otherwise, the KACLS will reject the decrypter’s attempts to decrypt exported content.
What you need
To configure KACLS access, make sure you have:
- An OAuth client ID that installed applications can use. Depending on your IdP, this client ID might be the same as the CSE web client ID set in the Admin console, or it might be a different client ID specific to installed applications. If your IdP is Google, the client ID for the decrypter must be a different client IDspecific to installed software.
- The OAuth client secret associated with the client ID, if your IdP is Google. You don't need the client secret if you're using a third-party IdP.
- The email address for the user account that authenticates to the KACLSfor export decryption. This can be your own account, or it can be a special account that your administrators have configured. You need to log in as this user when running the decrypter utility, so it's likely you'll need the account’s password.
KACLS endpoints
The KACLS configuration must allow the user account and client ID to call endpoints used for export decryption. Your KACLS administrator can usually set this up for you. The KACLS endpoint that's called by the decrypter depends on the type of encrypted content:
- Calendar CSE:
privilegedunwrap - Docs CSE, Sheets CSE, Slides CSE:
privilegedunwrap - Drive CSE:
privilegedunwrap - Gmail CSE (with S/MIME certificates):
privilegedprivatekeydecrypt - Gmail CSE (without S/MIME certificates):
privilegedunwrap
Configure Gmail S/MIME access (optional)
If you’re decrypting client-side encrypted Gmail messages that use S/MIME from Google Vault, the decrypter needs to call Gmail’s public API to download additional data. Google Vault exports don't include each user’s S/MIME certificates, so the decrypter automatically fetches them as needed from Gmail.
To allow the decrypter to request the S/MIME certificates for any user in your organization, you need to pass a domain-wide service account credential to the decrypter. For details on setting up this service account and creating a JSON file containing the private credential for the service account, go to Gmail only: Configure S/MIME for client-side encryption .
Note:This setup isn't required if you're decrypting client-side encrypted messages from the Data Export tool, or decrypting encrypted messages from Vault that don't have S/MIME certificates.
The decrypter can't fetch a user's S/MIME certificates and therefore can't decrypt client-side encrypted messages that use S/MIME if any of the following are true:
- The user account has been disabled or deleted
- S/MIME certificates on the account were removed
- Gmail API access is turned off
To help ensure decryption of client-side encrypted messages with S/MIME certificates, you can:
- Immediately decrypt messages exported from Vault while certificates remain available.
- Use the Data Export tool to export messages—these exports include each user’s certificates.
Create a configuration file first
The decrypter uses OAuth and your IdP to acquire an authentication credential that it includes on every KACLS privilegedunwrap
and privilegedprivatekeydecrypt
request. Your OAuth configuration won't change often, so you can create a configuration (config) file containing your OAuth settings to avoid having to set them each time you run the decrypter. For details on config file flags, go to Config creation flags
and Config update flags
below.
Note: Although this setup step is optional, it's recommended to simplify use of the decrypter utility. If you don't create a config file, you can instead pass the OAuth flags on the command line to every execution of the decrypter. If you do both, the flag values passed on the command line override values read from the configuration file.
Example: Create a config for the Google IdP
On Windows
> decrypter.exe -action createconfig -config C:\google-oauth.conf -email me@example.com -client_id my-client-id.apps.googleusercontent.com -issuer https://accounts.google.com
On macOS or Linux
$ ./decrypter -action createconfig -config ~/google-oauth.json -email me@example.com -client_id my-client-id.apps.googleusercontent.com -issuer https://accounts.google.com
Now you can update the config to add the OAuth client secret in the authorization code grant flow
On Windows
> decrypter.exe -action updateconfig -config C:\google-oauth.conf -client_secret my-client-secret
On macOS or Linux
$ ./decrypter -action updateconfig -config ~/google-oauth.json -client_secret my-client-secret
If your IdP isn't Google:Don't add the client secret, which is needed only by the Google IdP. Many other IdPs will reject authentication requests when the client secret is present.
Decrypt CSE files and email
The decrypter utility operates over unzipped export files.
- After you’ve created an export in the Data Export tool or Google Vault, download the zip files to your local computer.
- Unzip the files to a local directory or folder.
- Run the decrypter over the unzipped files and save the decrypted plaintext files to a different directory.
Example: Using a prepared config file without the service account credential
On Windows
> decrypter.exe -config C:\google-oauth.json -input C:\exported-files -output C:\decrypted-files
On macOS or Linux
$ ./decrypter -config ~/google-oauth.json -input ~/exported-files -output ~/decrypted-files
Example:Using a prepared config file with a service account credential
On Windows
> decrypter.exe -config C:\google-oauth.json -credential C:\serviceaccount.json -input C:\exported-files -output C:\decrypted-files
On macOS or Linux
$ ./decrypter -config google-oauth.json -credential serviceaccount.json -input exported-files -output decrypted-files
Example: Using neither a config file nor a service account credential
On Windows
> decrypter.exe -email me@example.com -client_id my-client-id.apps.googleusercontent.com -issuer https://accounts.google.com -client_secret my-client-secret -input C:\exported-files -output C:\decrypted-files
On macOS or Linux
$ ./decrypter -email me@example.com -client_id my-client-id.apps.googleusercontent.com -issuer https://accounts.google.com -client_secret my-client-secret -input ~/exported-files -output ~/decrypted-files
Decrypter flags
A decrypter flag can include either 1 or 2 leading hyphens—for example, the flag for displaying help information can be either of the following:
-help
--help
Note:You can use only hyphens for flags, not slashes (/).
Flags for string arguments can include either an equals sign or a space to specify the argument—for example, the following flags are equivalent:
-action=decrypt
-action decrypt
Help flags
| Flag | Description |
|---|---|
-version
|
Prints the version string. If you contact support, make sure you provide the version of the decrypter you're using. |
-help
|
Prints a screen of all flags for reference. |
-logfile
|
Specifies the output file where execution logs will be written. The text [TIMESTAMP] in the filename will be replaced with the execution start time. |
Decryption flags
| Flag | Description |
|---|---|
-action decrypt
|
Optional. Specifies that the utility's mode is to decrypt CSE files. This is the default mode. |
-email <email_address>
|
Optional. The email address that might be prepopulated in the IdP authentication screen that opens in the browser. |
-issuer <uri>
|
Required unless it's in the config file. The OAuth issuer discovery URI for the IdP, such as https://accounts.google.com. For details, go to Connect to identity provider for client-side encryption . |
-client_id <oauth_client_id>
|
Required unless it's in the config file. An OAuth client ID from the IdP specified in the -issuer
flag. For details, go to Connect to identity provider for client-side encryption
. |
-client_secret <oauth_client_secret>
|
Optional, although some IdPs may require it. The OAuth client secret part corresponding to the client ID specified in the -client_id
flag. |
-pkce
|
Enable or disable PKCE (Proof Key for Code Exchange) in the authorization code grant flow. If neither flag is specified, the decrypter defaults to enabled. |
-input <directory_or_file>
|
Required. The input directory or export file. If you specify a directory, the decrypter will recursively traverse the entire directory tree to find all exported CSE files. Use this option to bulk decrypt all exported files from an expanded export archive. If you specify 1 exported CSE file, the decrypter will decrypt just that file. If it's not a CSE file, the decrypter will request that you authenticate to the IdP but won't decrypt any files. |
-output <directory>
|
Required. The directory where decrypted files will be saved. |
-overwrite
|
Enables or disables overwriting of existing decrypted cleartext output files. If disabled (the default), the decrypter will skip decryption of ciphertext files if the cleartext file already exists. |
-workers <integer>
|
Optional. The number of parallel decryption workers. If you don't use this flag, the decrpyter defaults to the number of processor cores and hyperthreads reported by the operating system. If your computer has performance issues or you receive a multi-processing error when decrypting files, you can set this flag to 1 to disable parallel processing. |
-config <file>
|
Optional. A configuration file containing stored flag values. Use a config file to avoid pasting the same command-line flags whenever you decrypt files. For more information, go to Config creation flags and Config update flags below. Flag values you set on the command line take precedence over values in the config. Note:If you specify a file in the config and it's not found, an error occurs. |
-credential <file>
|
Optional. Specify a JSON file containing a domain-wide service account private key. When specified, decryption of Gmail CSE messages will query the Gmail API for each user's S/MIME certificates and key access control list service (KACLS) metadata. |
Config creation flags
-email <email_address>
|
Optional. Any specified flag values will be saved to the config file for reuse. |
|---|
Config update flags
Use these flags to update any flag values in a config file.
| Flag | Description |
|---|---|
-action updateconfig
|
Required. Overrides the default mode of execution to run the config file update mode. |
-config file
|
Required. The config file that you want to update. If the file doesn't exist, an error occurs. |
-email <email_address>
|
All optional. Values for flags you specify on the command line are overwritten; any other values for flags in the config are preserved. To unset a stored flag, specify a blank value. Note:If an edit corrupts the JSON format, an error will likely occur when you use the config in the decrypter. |
Informational flags
| Flag | Description |
-action info
|
(Required) Overrides default execution mode to run in informational mode |
-input directory_or_file
|
(Required) Specifies input directory or export file If you specify a directory, the utility recursively scans the entire directory tree looking for all CSE export files. If you specify a file, the utility gives information for just that file. You can repeat this flag to specify additional input directories or files. Example: |
