Decrypt exported client-side encrypted files and email (beta)

If your organization uses Google Workspace Client-side encryption (CSE), you can use the decrypter utility (beta) 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 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.

Note: When you decrypt a Google Docs, Sheets, or Slides file, the file name ends with .gdoc. The decrypter can’t convert these files to DOCX, XLSX, or PPTX yet.

System requirements

Microsoft Windows version 7, Vista, 8, 10, or 11 64-bit

Note: The decrypter will be available for Mac and Linux in an upcoming release.

Download the decrypter

Download the client-side decrypter utility to your computer.

Create a config file first

Because your CSE configuration won't change often, first create a config file so you can more quickly enter the flags you use. For details on config file flags, go to Config creation flags and Config update flags below.

Example: Create a config for the Google IdP:

> decrypter.exe -action createconfig -config C:\gaia-oauth.conf -email [email protected] -client_id my-client-id.apps.googleusercontent.com -issuer https://accounts.google.com

Then you can update the config to add the OAuth client secret in the authorization code grant flow:

> decrypter.exe -action updateconfig -config C:\gaia-oauth.conf -client_secret my-client-secret

Decrypt CSE files and email

After you create a config file, you can use it to decrypt exported files and email. To do this, run the decrypter over a directory of CSE files that have been unzipped, and then save the decrypted files to a different directory.

Drive example

> decrypter.exe -config C:\my_organization.conf -input C:\exported_files -output C:\decrypted_files

Gmail example

To decrypt Gmail CSE exports, you need to include a domain-wide credential:

> decrypter.exe -config C:\my_organization.conf -input C:\exported_files -output C:\decrypted_files -credential serviceaccount.json

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 -nopkce`	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 -nooverwrite`	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

Use these flags to save frequently used decryption command-line flags to a config file for reuse. A config file is formatted in JSON, which contains human-readable text.

Flag	Description
`-action createconfig`	Required. Overrides the default mode of execution to run the config file creation mode.
`-config file`	Required. Specify the output filename where you want to save the config. If the file already exists, it will be overwritten without a warning.
`-email <email_address> -discovery_uri <uri> -client_id <oauth_client_id> -client_secret <oauth_client_secret> -pkce -nopkce`	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.

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> -discovery_uri <uri> -client_id <oauth_client_id> -client_secret <oauth_client_secret> -pkce -nopkce`	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.

-email <email_address>

            -discovery_uri <uri>

            -client_id <oauth_client_id>

            -client_secret <oauth_client_secret>

            -pkce

            -nopkce

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

Use these flags to print readable information about CSE files.

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:

$ decrypter -action=info -input=file1.gcse -input=file2.gcse -input=file3.gcse

Was this helpful?

How can we improve it?