Google Workspace client-side decryption utility

=======

Run the decrypter from a command-line or terminal prompt:
> decrypter.exe [flags]
% ./decrypter [flags]
where [flags] contains decrypter flags described below. Flags may use either one or two leading hyphens. That is, -help and --help are equivalent. Flags on Windows are specified using hyphens as shown here, not slashes as used in some Windows command-line switches.
Flags that take a string argument may use either an equals sign or a space to delineate the argument. That is,
   -action=decrypt
and
   -action decrypt
are equivalent.

Users executing the decrypter utility must be authorized to call privileged endpoints of the key ACL service (KACLS). Endpoints required for each CSE product are as follows:
  * Calendar CSE: privilegedunwrap
  * Docs CSE: privilegedunwrap
  * Drive CSE: privilegedunwrap
  * Gmail CSE: privilegedprivatekeydecrypt, privilegedunwrap
Decrypter utility users should work with their KACLS administrator to ensure they have been granted access to these KACLS endpoints.

=======

System requirements

* Windows 10/11 64-bit
* Linux x86_64
* macOS 12 (Monterey) or later, x86_64 or M-series processor

=======

## Help flags

-version
Print the version string. If you need support, let us know what version you’re having difficulty with so that we can better assist.

-help
Print a usage screen of all flags. This is quite dense and can look overwhelming, but it's a helpful reference if you’ve forgotten a flag.

-logfile
Specify the output file where execution logs will be written. The special text [TIMESTAMP] in the filename will be replaced with the execution start time.


## Decryption flags

-action decrypt
Optional. Specify that the mode of execution of the tool is to decrypt CSE files. This is the default mode.

-email <email_address>
Optional. If specified, the IDP authentication screen that pops up in the browser may pre-populate the username with the specified email address.

-issuer <uri>
Required unless present in the config file. The OAuth issuer URI for the IDP, such as https://accounts.google.com.

-client_id <oauth_client_id>
Required unless present in the config file. An OAuth client ID from the IDP specified in the previous flag. This ID must be allowed to use the authorization code grant flow on the OAuth server, and it must be allowed by “aud” tests of the KACLS /takeout_unwrap perimeter.

-client_secret <oauth_client_secret>
Optional, though some IDPs may require it. The OAuth client secret part corresponding to the client ID specified in the previous flag.

-pkce
-nopkce
Enable or disable PKCE in the authorization code grant flow. If neither flag is specified, the decrypter defaults to enabled.

-port
Port number to use on localhost for OAuth2 callback. If not specified, a random available port will be chosen.

-input <directory_or_file>
Required. Specify the input directory or export file.
If specifying a directory, then the decrypter will recursively traverse the entire directory tree looking for all CSE export files. This is a good way to bulk decrypt all export files from an expanded Takeout archive.
If specifying a file, then just that one file will be decrypted. If it isn’t a CSE export file, then the decrypter will do nothing at all other than require you to authenticate to the IDP.
This flag may be repeated with each occurrence specifying an additional input directory or file.

-output <directory>
Required. Specify the directory where decrypted files should be saved.

-overwrite
-nooverwrite
Enable or disable overwrite of existing decrypted cleartext output files. If disabled (the default), the decrypter will skip decryption of ciphertext files if the cleartext file already exists.

-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 KACLS metadata.

-workers <integer>
Optional. Manually specify the number of parallel decryption workers. If unspecified, it defaults to the number of processor cores and hyperthreads reported by the operating system. This mostly exists as an emergency switch: set to 1 to forcibly disable concurrency if encountering non-determinstic or broken behavior due to buggy parallelism.

-config <file>
Optional. Specify a configuration file containing stored flag values so that you don’t need to repeatedly paste the same command-line flags across multiple executions. The next sections describe modes of execution for management of a config file.
Flag values explicitly set on the command-line take precedence over values read from the stored config.
It is an error if you specify a file and that file is not found.


## Informational flags
Print human-readable information about GCSE files to the standard output.

-action info
Required. Override the default mode of execution and instead run in informational mode.

-input <directory_or_file>
Required. Specify the input directory or export file.
If specifying a directory, then the utility will recursively traverse the entire directory tree looking for all CSE export files.
If specifying a file, then the utility will print information for just that one file.
This flag may be repeated with each occurrence specifying an additional input directory or file.


## Config creation flags
Save frequently-used decryption command-line flags to a config file for easy reuse.

-action createconfig
Required. Override the default mode of execution and instead run in config file creation mode.

-config file
Required. Specify the output filename where you want the config saved. If the file already exists, it will be overwritten without warning.

-email <email_address>
-discovery_uri <uri>
-client_id <oauth_client_id>
-client_secret <oauth_client_secret>
-pkce
-nopkce
-port
All optional. Any specified flag values will be saved to the config file for reuse.


## Config update flags
You can update an existing config by specifying new flag values. Previous saved values for those flags will be overwritten. Saved values for any other flags that you didn’t specify on the command-line will be preserved. You may unset a stored flag by assigning it an empty string.

-action updateconfig
Required. Override the default mode of execution and instead run in config file update mode.

-config file
Required. Specify the config file that you want to update. It is an error if the file does not exist.

-email <email_address>
-discovery_uri <uri>
-client_id <oauth_client_id>
-client_secret <oauth_client_secret>
-pkce
-nopkce
-port
All optional. Any specified flag values will be saved to the config file for reuse, overwriting any previous value. All unspecified flags will retain whatever value they already store in the config.

=======

Config file
The config file is a human readable and editable JSON file. If an edit corrupts the JSON format, then use of the config file in the decrypter will likely result in error.

=======

Example usage
Create a configuration for the Google IDP:
> decrypter.exe -action createconfig -config C:\gaia-oauth.json -email me@google.com -client_id my-client-id.apps.googleusercontent.com -issuer https://accounts.google.com

Then you can update the config to additionally supply the OAuth client secret in the authorization code grant flow:
> decrypter.exe -action updateconfig -config C:\gaia-oauth.json -client_secret my-client-secret
