Skip to content

Getting started

The Cosmian Key Management Server is compatible with Google Workspace client-side encryption. Using this feature, your users can encrypt files and documents, in their browsers, before sending them to Google servers. The ephemeral encryption keys are protected by “key wrapping keys”, stored in the KMS and unavailable to Google. Only users that have the right to unwrap the ephemeral encryption keys inside the KMS, can decrypt the files. An overview is provided in Google’s About client-side encryption page.

Info

To enable client-side encryption (CSE) in Google Workspace, connect as an admin to the admin console and go to the Google Workspace client-side encryption page.

Google has extensive documentation on how to enable CSE in Google Workspace. The Use client-side encryption for users’ data page is a good starting point. It may be slightly overwhelming, and this documentation adds some details to help you get started.

Prerequisites

Info

You will need:

Choosing the Certificate Authority

First you need an intermediate CA (Certificate Authority) that is trusted by Google and compliant with Gmail X509 expectations (read the expected X509 extensions).

This CA will issue your users certificates:

  • either your CA is one of the Google recommended CA, follow this page to make sure it is (note that Actalis can provide CA certificates for free). In that case, your users S/MIME certificates will be issued directly from your CA and you will need to import them one by one using Cosmian CLI
  • either this is a custom CA:
    • that you already have (remember that this custom CA must have the expected Google X509 extensions). You will have to upload the full CA chain in admin.google.com->Apps/Google Workspace/Settings for Gmail/User Settings/S/MIME (and wait for provisioning to be fully done, few hours expected).
    • that you do not have, in that case read this page to generate your own CA and upload the full CA chain in admin.google.com.

Choosing and configuring the Identity Provider

The first thing that will need to be done is to configure the Identity Provider. This is the service that the Cosmian Key Management Server will use to authenticate users before they can encrypt files or access encrypted files.

The Identity Provider (IdP) is either a third party IdP or Google identity.

Warning

Using Google Identity is not recommended since Google as the authority could issue tokens to impersonate users and recover their keys. However, since configuring an Identity Provider is hard and Google Identity is the easiest to configure, we will use it in this tutorial.

Enable CSE
Figure 1: Enable CSE

Important

The initial page should look like this. What matters here is the link shown at the tip of the red-arrow. This is the URL at which Google client-side encryption expects the .well-known file to be served. Assuming your domain is example.com, the URL will likely be https://cse.example.com/.well-known/cse-configuration.

To configure a .well-known file, you need to:

  1. Create the .well-known file with the proper content

  2. Set up a server that serves the file at the URL shown in the image above

Instructions are provided in the Configuring the .well-known file section

Once this is complete, the screen on refresh should turn to this:

IdP configuration is successful
Figure 2: IdP configuration is successful

Configuring the Key Management Server

The KMS must be behind a valid TLS certificate when started. Assuming it is running at https://cse.example.com, you should add the External Key Service with KACLS URL https://cse.example.com/google_cse in the Client-Side Encryption page of the Google Workspace admin console.

Important

To enable Client Side Encryption on the Cosmian KMS server, it must be started with the --google-cse-kacls-url option. This option is the URL at which the KMS will serve the Key Access Control Lists (KACLs) for the Google CSE service. The KACLs are used by the Google CSE service to determine which users have access to which keys. The KACLs are served by the KMS at the URL https://cse.example.com/google_cse in the example above.

The Key Management Server must be configured to use the same Identity Provider as the one configured in the previous step. When using Google Identity, the server should be configured with the following options set in the corresponding Google documentation.

Assuming Google is the Identity Provider, the KMS should be started with the following options:

--jwt-issuer-uri=https://accounts.google.com
--jwks-uri=https://www.googleapis.com/oauth2/v3/certs
--google-cse-kacls-url=https://cse.example.com/google_cse

For example, if you are using the docker image, you can run the following command:

docker run -p 9998:9998 --name kms ghcr.io/cosmian/kms:latest \
    --jwt-issuer-uri=https://accounts.google.com \
    --jwks-uri=https://www.googleapis.com/oauth2/v3/certs \
    --google-cse-kacls-url=https://cse.example.com/google_cse

external keys service
Figure 3: external keys service

Then test the connection; it should show:

external key service ok
Figure 4: external key service ok

Finalize the configuration. The Client Side Encryption page should now show the service to be active and you will now have to decide whether to assign this service to all users or to a subset of users.

Cosmian KMS active
Figure 5: Cosmian KMS active

Creating google_cse key

Once your CSE Cosmian KMS is up and running, you need to import the AES wrapping key, which will be responsible for wrapping the keys managed by Google. This key MUST be created under the google_cse ID.

Using the Cosmian CLI, ensure that it is properly configured and that authentication is handled correctly.

Important

Concerning the Cosmian CLI, you will have to log in the first time you use it. This is done by running cosmian kms login.

# create it
cosmian kms sym keys create -t google_cse google_cse

# or import an existing key
cosmian kms sym keys import -t google_cse PATH_TO_YOUR_KEY google_cse

Next, you’ll need to assign access rights to each user who requires CSE functionality, whether they are part of your organization or a guest. You can also grant wildcard access (‘*’) to allow all users to use this key in CSE endpoints.

cosmian kms access-rights grant USER_ID google_cse get encrypt decrypt

# or give access to everyone
cosmian kms access-rights grant '*' google_cse get encrypt decrypt

Handling Guest identity providers

As an administrator, you can allow external users to access your encrypted content via Google Workspace Client-Side Encryption (CSE), including sharing encrypted documents or hosting encrypted Google Meet sessions.

For more information on this configuration, refer to Google documentation.

Cosmian KMS supports this feature, and to enable it:

  • Add the identity provider’s information in the server-side Cosmian KMS configuration
  • Ensure that external users can access the Google CSE symmetric key

User experience

Learn more details about CSE user experience over all supported applications.

© Copyright 2018-2024 Cosmian. All rights reserved.