FlowCrypt Google Workspace Key Manager Technical Overview

version: 2024-02

This software allows you to protect your organization’s Google Workspace data with strong Client-Side Encryption (CSE).

The Google Workspace Key Manager (WKM) is a server software service that wraps and unwraps (encrypts and decrypts) Data Encryption Keys (DEKs) for use in Google Workspace web and native applications, such as Google Drive, Google Docs, and more.

Your company deploys the software to a server, running either on your premises or in the cloud. You don’t need to install any special programs or add-ons on user workstations, and no regular actions are required by users, only regular maintenance of the server by your IT department. Additionally, FlowCrypt offers this software as a SaaS solution, where you don’t need to worry about maintaining servers, as we manage everything for you.

The app is based on Key Encryption Keys (KEKs) derived on the fly using a set of master secrets, which, in turn, may be stored using your existing infrastructure on any PKCS#11 or KMIP-compatible Hardware Security Module (HSM) or software Key Management System (KMS). KEK-encrypted Data Encryption Keys (DEKs) are then uploaded to GSuite along with the encrypted data.

The API is a REST API with JSON body requests and responses, accessed by the Google Workspace web app and Google Workspace client software. SSL connections can be either terminated in the WKM or by using an SSL terminating reverse proxy. In the latter case, you can set the api.https.enabled property to false in the config file.

Requirements

All the requirements described in the Enterprise Server Deployment Requirements plus the following:

Distribution and deployment

FlowCrypt WKM is distributed as a zip file containing:

For deployment, install OpenJDK 17, copy the .jar and the .properties files, and edit the latter before running.

Windows only: If your OS doesn’t use a UTF-8 file encoding by default, you should ensure that the app uses the UTF-8 encoding. UTF-8 support is required by the Google Workspace CSE KACLS. The easiest way to do this is to set the JAVA_TOOL_OPTIONS environment variable to -Dfile.encoding=UTF8. Alternatively, when starting the application, you can add the encoding system property to the java -Dfile.encoding=UTF-8 -jar flowcrypt-workspace-key-manager.jar startup command.

How to run the application

Before you run the application, you have to set up your master secrets. See the section on how to generate master secrets for this purpose.

Once your master secrets and other properties are configured, start the WKM by running the java -jar flowcrypt-workspace-key-manager.jar command.

The default command is to start the server at the localhost:32567 address. Other commands are:

Command line options:

Configuration

The sample configuration file, appropriate for your software version, will come distributed along with the jar file. It consists of several sections: Common, Store, Logger, Authentication, Google Workspace, and ACL. Each section is described in detail below:

• Logging
• High Availability and Scaling
• Deployment Checklist

Configuration: Common

See the Enterprise Server General Configuration and HTTPS guide for more detailed information.

Configuration: Store

The WKM needs to be set up with a master key and a test vector. All individual object (cloud file) keys are then derived from these master secrets on the fly. To generate your master secrets, run the following command:

$ java -jar flowcrypt-workspace-key-manager.jar --create-master-key

This command will generate a master key and print out the associated test vector for you:

The retrieval options can and should be combined. For example, for high security, you could have one secret stored over KMIP and another one supplied manually during WKM startup. On the other end of the spectrum, for ease of setup and convenience, you could supply both values in the properties file.

If you’ve chosen kmip or pkcs11 for any of the source properties, you also need to tell WKM how to connect to such a store to retrieve the master key.

KMIP integration

Our implementation is tested against the PyKMIP server. While KMIP is a vendor-agnostic protocol, implementations do vary from vendor to vendor. When planning a PoC, please allocate sufficient time for us to test against and integrate with your particular KMIP vendor.

KMIP authentication

KMIP authentication operates as follows. The server (your key store or HSM) as well as the client (in this case, WKM) possess their own TLS certificates. Each certificate must be mutually trusted to establish a connection. When configuring WKM, you can use the truststore.file property to point to a file containing trusted certificates. These certificates are used to validate the KMIP server’s credentials, preventing man-in-the-middle (MITM) attacks. Likewise, your KMIP server should be configured to strictly verify the client’s certificate.

PKCS#11 integration

We develop and test our implementation against Equinix SmartKey (Fortanix SDKMS). For this purpose, we used their PKCS#11 shared .so library module, accessed through the iaik.pkcs.pkcs11.wrapper Java library. To connect our software to your PKCS#11 HSM, update the store.pkcs11.module property to point to the module provided by your HSM vendor.

To test your PKCS module, you can use the pkcs11-tool utility on Ubuntu:

$ sudo apt-get -y install opensc
$ pkcs11-tool --module vendor-pkcs11.so --show-info

After, set the following properties in the properties file:

Test store connection

To test that the WKM can retrieve master secrets and they’re valid, run this command:

java -jar flowcrypt-workspace-key-manager.jar --test-store-connection

This will validate a test vector to make sure the Store is properly set up. The command returns status 0 on Unix systems when successful.

The successful output looks like the following:

Registering StdoutLogger as a Logger implementation
INFO  Reflection - Registering MasterKeyStore as Store implementation
INFO  MasterKeyStore - Successfully validated MasterKeyStore Test Vector
INFO  c.f.keymanager.TestStoreConnection - initiating test
INFO  c.f.keymanager.TestStoreConnection - success

Configuration: Authenticator

The authenticator component configures an OpenId Connect service which verifies non-Google-issued JWTs (JSON web tokens), asserting the identity of the user who accesses an object.

First, you need to decide if you want to use Google as your IdP or if you want to use your own. Then, set up an OpenID Connect (OIDC) authentication app on your IdP as follows:

IdP-specific instructions:

• OneLogin: Applications ⮕ Add App ⮕ find and choose the OpenId Connect (OIDC) app from OneLogin, Inc. ⮕ name it FlowCrypt WKM App ⮕ Save. When done, go to Applications ⮕ select FlowCrypt WKM App from the list of apps ⮕ on the left menu, select Configuration, and fill in the Redirect URI’s field with the Redirect/callback URLs mentioned above ⮕ Next, click on the SSO on the left menu and take note of the pre-generated client ID and Issuer URL for your app. There are the fields to put into the WKM properties file: Client ID (put into auth.enduser.default.audience and auth.admin.default.audience), Issuer URL V2 (put into auth.enduser.default.issuer and auth.admin.default.issuer), and V2 .well-known URL. Make sure all of your users can access this newly created application by implementing a rule, policy, or another such mechanism on OneLogin.
• Google Developer Console: console.developers.google.com ⮕ the top left project selector ⮕ NEW PROJECT ⮕ FlowCrypt-WKM. Next, new OAuth Consent Screen ⮕ internal, add a name and logo as above, authorized domains: google.com. Finally, in the left menu choose Credentials ⮕ + CREATE CREDENTIALS ⮕ OAuth Client ID ⮕ Web Application ⮕ fill in the JavaScript origins and redirect URI as above ⮕ CREATE. You’ll get your Client ID on the next screen (the client secret isn’t needed).

Next, connect your IdP with Workspace CSE. You have two options to choose from, either hosting a /.well-known/cse-configuration file or connecting to your IdP using the Admin console. For more information, please refer to the Connect to your identity provider for client-side encryption guide.

If you choose to connect to your IdP using a hosted /.well-known/cse-configuration file, you need to add the following CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET

To verify that you’ve added CORS headers properly, you can use the curl utility as follows:

curl -Is https://cse.subdomain.domain.tld/.well-known/cse-configuration

Make sure to adjust the path to match your own.

Configuration: Authenticator for Google Desktop and Mobile apps

With the IdP connection, you can also enable client-side encryption for Google Drive Desktop and selected mobile applications such as Google Drive, Google Calendar, Gmail, and Google Meet. These applications can be downloaded from the Google Play Store and Apple App Store.

Redirect/callback URLs for Desktop and Mobile apps:

Please make sure to set the Authentication Method of the authentication app to (None) PKCE.

If you’re using a third-party IdP, your .well-known file should look like this:

{
  "name": "name of your IdP",
  "client_id": "ID from IdP",
  "discovery_uri": "https://your_idp.com/.well-known/openid-configuration",
  "applications": {
    "drivefs": {
      "client_id": "ID from IdP"
    },
    "drive-android": {
      "client_id": "ID from IdP"
    },
    "drive-ios": {
      "client_id": "ID from IdP"
    },
    "calendar-android": {
      "client_id": "ID from IdP"
    },
    "calendar-ios": {
      "client_id": "ID from IdP"
    },
    "gmail-android": {
      "client_id": "ID from IdP"
    },
    "gmail-ios": {
      "client_id": "ID from IdP"
    },
    "meet-android": {
      "client_id": "ID from IdP"
    },
    "meet-ios": {
      "client_id": "ID from IdP"
    }
  }
}

Otherwise, you can set it in the IdP fallback settings on Google Admin. To access it, go to Security ⮕ Client-Side Encryption ⮕ IdP fallback settings. Scroll down to the Authentication for Google desktop and mobile apps section, tick the checkboxes for each Google app, and set the client ID that you created for each Google app.

For detailed instructions, please check the corresponding guide by Google.

Configuration: Google Workspace

The GSuite authorization component configures the Google OpenId Connect service which verifies Google-issued JWTs, making sure the user requesting access to a particular object is allowed to access it.

Configuration: Gmail CSE

To use Google Workspace Client-side encryption (CSE) for Gmail, you need to upload an S/MIME certificate and private key metadata for each user using the Gmail API. You can find a full guide for configuring the Gmail CSE on the Google Workspace Admin Help portal.

To simplify this process, we created a script that extracts a private key from an S/MIME certificate, wraps it, and uploads it along with the certificate to Gmail. You can use it by running the --upload-mail-certificate command:

$ java -jar flowcrypt-workspace-key-manager.jar --upload-mail-certificate --pfx-path PFX_CERTIFICATE_PATH --pfx-password PFX_CERTIFICATE_PASSWORD --config=CONFIG_FILE_PATH

For Gmail API authorization, we need a Google service account key. You can get it by creating a service account and adding a service account key to it. After you’ve downloaded the JSON file with a service account key, please update your configuration file with these properties:

Configuration: Migration

The GSuite KACLS interaction component configures which other KACLS servers can be accessed and accessed by.

Configuration: ACL

The ACL component allows third-party implementations to further protect resources.

Please email us at human@flowcrypt.com to use a 3rd party ACL.

Troubleshooting

Because the Google CSE combines its own systems with your existing IdP and our WKM, which in turn may rely on your KMIP or PKCS11 store, each with various configuration options, you may run into issues the first time you attempt to configure all these together.

To troubleshoot the WKM startup, it’s recommended to first read the Troubleshooting guide.

Troubleshooting Google Alpha CSE

In this early stage of Google CSE, you may encounter unintuitive errors with no clear resolution guidance, such as the ones described below:

For help or to report issues, please email us at human@flowcrypt.com.

• Error 404 (Not Found) on the callback URL. If during testing you’re facing an Error 404 when your IdP redirects to this URL after the login (for example, when you’re uploading a new file), this can have one of the following causes:

  • (during Google Alpha) Google needs to whitelist your user or issuer.
  • (during Google Alpha) You signed in to multiple Google accounts, and the test user isn’t the default user on your browser. Try to log out of all accounts and sign in only to the target test account. Alternatively, use Incognito mode in Chrome and log in with only the target test account.

• An error occurred with the identity provider service. This can manifest as an error saying “An error occurred with the identity provider service”, or “Can’t decrypt the file (Something went wrong and your file wasn’t downloaded)”, or “An error occurred with identity provider service”. There are two possible causes:

  • (during Google Alpha) Your browser hasn’t authenticated with your IdP within drive.google.com yet. To authenticate during Alpha, upload a drive file first instead, go through an Upload failure, and force re-authentication as described below. Then you can go back to your original task (opening file, updating doc, etc.).
  • Your IdP is misconfigured, such as the user you’re logged in with wasn’t assigned to the IdP app, or the wrong Client ID in the cse-configuration, etc. To debug, you can observe the browser network tab, or ask Google.

• Upload failure. You can see an Upload failure on drive.google.com when you’re uploading an encrypted file and haven’t been authenticated on this browser yet. To resolve, click the ! exclamation mark in a red circle shown with this error. This will force to start a re-authentication process. Re-authenticating through the upload flow of the encrypted file will fix other authentication issues around the Drive/Docs apps that don’t have their own robust authentication error handling mechanism yet.

Sample config file

# docs:
# https://flowcrypt.com/docs/technical/workspace-key-manager/latest/technical-overview.html

### General ###

org.id=evaluation.org

api.hostname=0.0.0.0
api.port=32567
api.accept.hosts=localhost:32567
api.https.enabled=true
api.https.key.file=wkm-https-cert.p12
api.https.key.password=password
api.cors.origins=https://admin.google.com,https://krahsc.google.com,https://client-side-encryption.google.com
api.url=https://wkm.evaluation.org
api.url.add.to.accept.hosts=true
#api.error.format=detailed|short|id_only
api.error.format=id_only
api.openapi.enabled=false

# The truststore is optional. If you want to override the default JRE truststore,
# use this to verify the KMIP server with a custom certificate.
#truststore.file=wkm-dev-rootca.p12
#truststore.password=password
#truststore.include.default=true

### Store ###

# The options for the "key.source" field are: properties | stdin | kmip | pkcs11
# The only option for "test.vector.source" is: properties
# The required key format is 32 bytes (256 bits) of random data encoded as base64
# Generate master secrets, and test vector by running: --create-master-key (uses Java SecureRandom, or KMS over KMIP)

store.type=MasterKeyStore
store.master.derivation.scheme=sha256-aes-ecb
store.master.key.source=properties
# Enter the "--create-master-key" output (master key) here to set the master key in the properties file.
store.master.key.value=
store.test.vector.source=properties
# Enter the "--create-master-key" output (test vector) here either way. This is used to cross-check the entered key.
store.test.vector.value=

# The master key stored in secure key storage over KMIP protocol (e.g. Gemalto Safenet KeySecure).
# Remember to also set the `truststore.file` above if the KMIP server uses certificates with custom CA.
#store.kmip.hostname=localhost
#store.kmip.port=5696
#store.kmip.key.file=localhost.p12
#store.kmip.key.password=password
#store.kmip.master.key.name=flowcrypt-workspace-km-master-key
#store.kmip.master.key.identifier=

# The master key stored over PKCS#11 protocol such as Fortanix SDKMS, Equinix SmartKey, or any compatible HSM.
#store.pkcs11.module=./vendor-pkcs11.so
#store.pkcs11.pin=file://vendor-pkcs11.cfg


### Logger ###

# A comma-separated list. Can have any combination of StdoutLogger, FileLogger, StackdriverLogger, SplunkHttpLogger
logger.types=StdoutLogger
# trace, debug, info, warn, error
logger.default.level=info
#logger.stdout.include.datetime=true
#logger.file.folder=/var/logs
#logger.file.history.size=14
#logger.file.history.compression=false
#logger.file.include.datetime=true
#logger.stackdriver.credentials.file=/etc/google/auth/application_default_credentials.json
#logger.splunk.url=https://splunk-instance:8088
#logger.splunk.token=327bfa46-...
#logger.splunk.disable.certificate.validation=true


### Authentication ###

# Use the defaults provided below, if you intend to use Google as your IdP. In that case, set up an
# oAuth Screen on Google Developer Console, and provide an oAuth Client ID in the audience field.
# Otherwise, change the issuer and the JWKS to your custom company IdP.
auth.enduser.idps=default
auth.enduser.default.issuer=https://accounts.google.com
auth.enduser.default.audience=SET_YOUR_GOOGLE_OAUTH_CLIENT_ID_HERE
auth.enduser.default.jwks=https://www.googleapis.com/oauth2/v3/certs

auth.admin.idps=default
auth.admin.default.issuer=https://accounts.google.com
auth.admin.default.audience=SET_YOUR_GOOGLE_OAUTH_CLIENT_ID_HERE
auth.admin.default.jwks=https://www.googleapis.com/oauth2/v3/certs

### Authorization ###

### privileged users for requests requiring authentication without Google authorization ###
google.workspace.privileged.users=

### Google Workspace Products ###
google.workspace.products=drive,meet,calendar,gmail,migration

### Google Workspace Authorization (Docs & Drive) ###
google.workspace.drive.product.family=default
google.workspace.drive.issuer=gsuitecse-tokenissuer-drive@system.gserviceaccount.com
google.workspace.drive.audience=cse-authorization
google.workspace.drive.jwks=https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-drive@system.gserviceaccount.com

### Google Workspace Authorization (Meet) ###
google.workspace.meet.product.family=default
google.workspace.meet.issuer=gsuitecse-tokenissuer-meet@system.gserviceaccount.com
google.workspace.meet.audience=cse-authorization
google.workspace.meet.jwks=https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-meet@system.gserviceaccount.com

### Google Workspace Authorization (Calendar) ###
google.workspace.calendar.product.family=default
google.workspace.calendar.issuer=gsuitecse-tokenissuer-calendar@system.gserviceaccount.com
google.workspace.calendar.audience=cse-authorization
google.workspace.calendar.jwks=https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-calendar@system.gserviceaccount.com

### Google Workspace Authorization (Gmail) ###
google.workspace.gmail.product.family=gmail
google.workspace.gmail.issuer=gsuitecse-tokenissuer-gmail@system.gserviceaccount.com
google.workspace.gmail.audience=cse-authorization
google.workspace.gmail.jwks=https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-gmail@system.gserviceaccount.com

### Google Workspace Authorization (migration) ###
google.workspace.migration.product.family=default
google.workspace.migration.issuer=apps-security-cse-kaclscommunication@system.gserviceaccount.com
google.workspace.migration.audience=cse-authorization
google.workspace.migration.jwks=https://www.googleapis.com/service_accounts/v1/jwk/apps-security-cse-kaclscommunication@system.gserviceaccount.com

### Google Service Account ###
google.service.account.client.id=
google.service.account.client.email=
google.service.account.private.key.pkcs8=
google.service.account.private.key.id=

### ACL ###

acl.type=NoThirdPartyAcl

### Migration ###

# Only KACLS URLs defined in these properties will be allowed incoming and outgoing access.
# It is recommended to leave these undefined until there is a need to migrate from one instance to another.
#kacls.incoming.url.whitelist=https://incoming.kacls.test
#kacls.outgoing.url.whitelist=https://outgoing.kacls.test

# Allows /certs and privileged unwrap KACLS calls to remain consistent over multiple servers & between restarts.
# Create using the --create-migration-key console command.
#kacls.migration.key=