Using Fortanix DSM for Google Workspace Client-Side Encryption

1.0 Introduction

This article describes how to use Fortanix Data Security Manager (DSM) for Google Workspace Client-Side Encryption (CSE).

To perform Google Workspace CSE using Fortanix DSM, you will encrypt the Google Workspace applications’ data (such as Google Docs and Google Drive) with a Data Encryption Key (DEK) and use Fortanix DSM API to wrap the DEK before storing it on Google Cloud storage. To decrypt the document, the Google Workspace application will call the Fortanix DSM APIs to unwrap the DEK and then decrypt the data.

2.0 Definitions

• CSE – Client-Side Encryption:

  With Google Workspace Client-side encryption (CSE), file encryption is handled in the client's browser before it is stored in cloud storage. That way, Google servers cannot access your encryption keys and, therefore, cannot decrypt your data. To use CSE, you'll need to connect Google Workspace to an external encryption key service and an identity provider (IdP). Refer to Google Documentation for more details.

• AES – Advanced Encryption Standard:

  Google uses the Advanced Encryption Standard (AES) algorithm to encrypt data at rest. AES is widely used because:

  • Both AES256 and AES128 are recommended by the National Institute of Standards and Technology (NIST) for long-term storage use (as of November 2015).
  • AES is often included as part of customer compliance requirements.
    For more information please see Advanced Encryption Standard.

3.0 Prerequisites

• Fortanix DSM must be set up as the encryption key service.
• An Identity Provider (IdP) - you need to connect to either an external IdP configured on your Google Workspace account, or Google identity by creating a client ID in the Google Cloud Platform (GCP) console. Your IdP verifies the identity of users before allowing them to encrypt files or access the encrypted files.
• An Authorization Provider – Configure an authorization provider to enable CSE for Google Docs and Google Drive. This is used to verify information such as the caller’s role, resource name, and so on.
• AES key – The key that wraps and unwraps the DEK.
• For single KEK:
  https://<dsm_domain>/crypto/v1/keys/<key_id>/integrations/workspace_cse
• For separate KEK for each document:
  https://<dsm_domain>/crypto/v1/groups/<group_id>/integrations/workspace_cse
  Where,
  • <dsm_domain> is the fully qualified domain name of your Fortanix DSM cluster, for example: “smartkey.io” for DSM SaaS.
  • <key_id> is the UUID of the KEK in Fortanix DSM.
  • <group_id> is the UUID of the group where you want to store KEKs for Google Workspace applications.

After you decide which approach suits your needs best, you should note the correct URL by putting in the correct values for the parameters specified above and move on to configuring CSE in the Workspace admin console. 

4.0 Key Management Best Practices

For key rotation, you need to perform the following steps:

• Rotate the key in Fortanix DSM
• Copy the URL for the new key (the id will be different)
• Change the URL in Workspace CSE

Workspace CSE will use the new key to encrypt but can still decrypt old data that was encrypted with the old key (if you delete the old version).

When using a URL containing a Group ID, you do not need to do anything other than rotate the key in Fortanix DSM.

5.0 Fortanix DSM with Google Workspace

5.1 Overview

Google Workspace CSE encrypts user’s documents before it leaves their web browser. The Workspace application, for example: Google Docs, generates a Data Encryption Key (DEK) in the browser, encrypts user contents with that key, and then it calls Fortanix DSM to wrap the DEK with a key in Fortanix DSM. It then stores the encrypted data along with the wrapped DEK in cloud storage. When calling the Fortanix DSM APIs, the Workspace application presents two signed JSON Web Tokens (JWT) with its request that identifies the user by their email address used to log in to the Google Workspace application.

Fortanix DSM will verify these JWT tokens based on the account CSE configurations and check whether the user has proper access to the Key Encryption Key (KEK) before wrapping/unwrapping the DEK.

Google Workspace CSE requires the following APIs from Fortanix DSM:

• Wrap: POST https://<base_url>/wrap
• Unwrap: POST https://<base_url>/unwrap
• Privileged Unwrap: POST https://<base_url>/privileged_unwrap
• Status Check: GET https://<base_url>/status

  Where <base_url> either identifies a single key or a group in Fortanix DSM. When using a single key, all DEKs are encrypted with the same KEK. When using a group, each Google Workspace document’s DEKs will be encrypted with its own dedicated KEK stored in the specified group in DSM and the KEKs are created automatically when wrap API is called to encrypt a document. The URL patterns for each case are:

• For single KEK:
  https://<dsm_domain>/crypto/v1/keys/<key_id>/integrations/workspace_cse
• For separate KEK for each document:
  https://<dsm_domain>/crypto/v1/groups/<group_id>/integrations/workspace_cse
  Where,
  • <dsm_domain> is the fully qualified domain name of your Fortanix DSM cluster, for example: “smartkey.io” for DSM SaaS.
  • <key_id> is the UUID of the KEK in Fortanix DSM.
  • <group_id> is the UUID of the group where you want to store KEKs for Google Workspace applications.

After you decide which approach suits your needs best, you should note the correct URL by putting in the correct values for the parameters specified above and move on to configuring CSE in the Workspace admin console. But in order to enable CSE in your Fortanix DSM account, you need to follow the steps in the next section.

5.2 Configure Workspace CSE in Fortanix DSM

1. Log in to Fortanix DSM as an account administrator and click the Settings tab in the left panel.
2. On the Account Settings page, click WORKSPACE CSE in the left menu.
3. In the Workspace CSE Client-Side Encryption page, click CONFIGURE to configure the Workspace CSE for the account. Figure 1: Configure Workspace CSE

5.2.1 Configure Identity Providers

Configure the Identity Providers that authenticate users for Google Workspace.

1. Enter the following details
   • Identity Provider name: choose a descriptive name for the IdP.
   • Signing keys: Either STORED or FETCHED. This is used to validate the signature on the authentication JWT.
     • STORED:
       • Public key: provide one or more public keys by uploading or pasting the key(s) in PEM format. When specifying multiple keys, specify the Key ID so that keys can be differentiated by their unique Key IDs.
     • FETCHED:
       • Key URL: specify a URL where the signing keys can be fetched from. The specified URL should return the signing keys in one of the following formats:
         • JWK Set: please refer to Section 5 of RFC 7517 for details.
         • A JSON object mapping key IDs to base64 encoded public keys in DER format. Here is an example:
       • Cache duration: To improve performance, Fortanix DSM will cache the fetched keys, but you can control how long the keys are cached.
   • Valid issuers: one or more valid issuers. This information is used to validate the iss field of the JWT.
   • Valid Audiences: one or more valid audiences. This information is used to validate the aud field of the JWT.
   It is recommended to use fetched signing keys if the signing keys are rotated periodically. Figure 2: Stored signing key authentication Figure 3: Upload public key(s) Figure 4: JWT fetched signing key authentication
   If you are not using any external IdP with your Workspace account, then use the following values for the identity provider:
   • Identity Provider name: Google
   • Signing keys: FETCHED
     • Key URL: https://www.googleapis.com/oauth2/v3/certs 
     • Cache duration: 86400 seconds (1 day)
   • Valid issuers: https://accounts.google.com 
   • Valid audiences: you need to follow the instructions in “Create a client ID for Google identity” and copy the OAuth client ID you created here. Figure 5: JWT fetched signing key authentication

   For third-party IdPs follow the instructions in Connect to identity provider for client-side encryption and provide the same information that you use when configuring your IdP in the Workspace admin console - option 2 (or from the .well-known document of your IdP - option 1)

2. Click NEXT to configure the Authorization Providers.

5.2.2 Configure Authorization Providers

Configure one or more authorization providers that allow the service to validate the Google-issued authorization tokens for Workspace CSE APIs. Different Workspace applications might require different authorization settings.

1. Select Google Drive and Docs if you want to configure this option as an authorization provider. The authorization provider settings will be automatically included for Google Drive and Google Docs.
   If you want to add another authorization provider, then:
2. Click ADD ANOTHER AUTHORIZATION PROVIDER. Figure 6: Add another authorization provider
   1. Enter a name for the provider.
   2. Key URL: Enter the remote public key location.
   3. Cache duration: To improve performance, Fortanix DSM will cache the keys, but you can control how long the keys are cached.
   4. Valid issuers: One or more valid issuers. This information is used to validate the iss field of the authorization JWT. For example, gsuitecse-tokenissuer-drive@system.gserviceaccount.com  is used for Google Drive and Docs.
   5. Valid Audiences: One or more valid audiences. This information is used to validate the aud field of the authorization JWT. For example, cse-authorization is used for Google Drive and Docs.
   Figure 7: Configure authorization provider
   Configure Google Meet as an Authorization Provider:
   
   • Key URL: https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-meet@system.gserviceaccount.com 
   • Cache duration: 86400
   • Valid issuers: gsuitecse-tokenissuer-meet@system.gserviceaccount.com 
   • Valid Audiences: cse-authorization
   Configure Google Calendar as an Authorization Provider:
   
   • Key URL: https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-calendar@system.gserviceaccount.com 
   • Cache duration: 86400
   • Valid issuers: gsuitecse-tokenissuer-calendar@system.gserviceaccount.com 
   • Valid Audiences: cse-authorization
3. Click NEXT to review the listing.
4. Click SAVE to save the Workspace Client-Side Encryption settings.
5. Create an AES key in the same Fortanix DSM account and copy its UUID. Or if you prefer separate keys for your Workspace documents, create a group in Fortanix DSM and copy its UUID.

For steps to create an AES key, refer to Section 6.0: Appendix.

5.3 Enable Google Workspace  to Access Keys in Fortanix DSM

Google Workspace CSE needs a URL to access the KEK stored in Fortanix DSM:

• For single KEK, use the following pattern replacing <key_id> and <dsm_domain> with appropriate values:
  Figure 8: Copy key UUID
  

  https://<dsm_domain>/crypto/v1/keys/<key_id>/integrations/workspace_cse

• For separate KEK for each document, use the following pattern replacing <group_id> and <dsm_domain> with appropriate values:
  

  https://<dsm_domain>/crypto/v1/groups/<group_id>/integrations/workspace_cse

For example, if you have created a group in your DSM SaaS account with UUID e3e2a600-96cd-4b5c-b0b9-22a9cfbf3b2b, you will use the following URL:
https://amer.smartkey.io/crypto/v1/groups/e3e2a600-96cd-4b5c-b0b9-22a9cfbf3b2b/integrations/workspace_cse

Use the above resource URL in your Workspace admin console as your “key service URL”.

1. Log in to google.com with an administrator account and click Security -> Client-side encryption.
2. Under Add external key service:
   1. Enter a name for the external key service, provide the URL that you copied in the above step, and then click Continue.
   2. Click TEST CONNECTION and make sure the connection is successful.
   3. Click Add Service -> Continue to finish the configuration.
3. Under Add identity provider, enter the details of the well-known identity provider that you provided in Fortanix Google CSE settings in Section 5.2.
   • Name: Enter a name
   • Client ID: Enter the OauthID that you added to Fortanix DSM in Section 5.2.
   • Discovery URI: https://accounts.google.com/.well-known/openid-configuration
   • Grant type: Implicit
4. Click TEST CONNECTION and make sure the connection is successful.
5. Click Add Provider to add the IdP.
6. Under Apps, click the Drive and Docs icon:
   1. Client-side encryption status -> Turn it ON
   2. Default external key service -> Select the newly added key service from drop down

Figure 9: Add External Key Service and Identity Provider

After completing the Workspace settings, follow the steps listed in About client-side encryption - Google Workspace Admin Help. You should be able to go to Google Docs and create an encrypted document, if everything works you will see audit log messages on the key(s) in DSM showing requests coming from your browser.

6.0 Appendix

6.1 Create/Import an AES Key

In your Fortanix DSM console, follow the process below to create/import an AES encryption key:

1. Click the Security Objects  tab (Figure 10).
2. Click to create a new Security Object.
   Figure 10: Security Objects tab in Fortanix DSM
3. In the Add New Security Object form, you can create or import an AES key. See the example below to import an AES key (Figure 11):
   Figure 11: Create/Import AES key
   1. Type a name for the Security Object (Key).
   2. Click Import to set the option to import an AES key.
   3. Click AES for the type of key to import.
   4. Select an option for the key-value format.
   5. Click UPLOAD A FILE to upload your AES key.
   NOTE

   Make sure the new key has “encrypt” and “decrypt” key operations allowed.

   To generate a new AES key, follow the instruction below (Figure 12):

   Figure 12: Generate a New AES key

   1. Type a name for the Security Object (Key).
   2. Click Generate to set the option to generate an AES key.
   3. Click AES for the type of key to import.
   4. Type a value for the key size, in the Key size
   5. Select the permitted key operations for this key.
   6. Assign a group for the key.
   7. Select Audit log to enable audit logging. This will inform you about all the audit logging for this security object. it is an optional field.
   8. Click Generate to generate the AES key.

7.0 Frequently Asked Questions

• How to identify the security object associated with the Google document when using Group ID?
  When using Group ID, Fortanix DSM creates a security object for each document that is encrypted from Google CSE and you can identify the security object associated with a document in Fortanix DSM by clicking on the encrypted document in Gdrive and paying close attention to the document URL that contains the security object.  
• How can I segregate the security objects created by multiple teams in Google Workspace since all the security objects are created in a single group in Fortanix DSM when using Fortanix DSM Group ID in KMS URL?
  When using Group ID in KMS URL, all the security objects are created in the default group. However, you can create multiple groups, for example HR, Finance, IT, and so on, and move the associated security objects manually to the new group from the default group.
  One point to note is that when you move an object to a different group, users still need to be group admin in that group to be able to use the key to wrap/unwrap, otherwise they would get an access control error. This security requirement is the best way to restrict all the users having permissions to decrypt documents in all the security objects they are not supposed to.