Gmail only: Upload encryption keys for client-side encryption

Supported editions for this feature: Enterprise Plus; Education Standard and Education Plus. Compare your edition

To use Google Workspace Client-side encryption (CSE) for Gmail, you need to enable the Gmail API and give it access to your entire organization. Then, for each user, you need to use the Gmail API to upload an S/MIME (Secure/Multipurpose internet Mail Extensions) certificate (public key) and private key metadata to Gmail. If you're using a encryption key service, you'll also need to encrypt (or "wrap") users' private key metadata using your key service.

At any time, you can switch to a different key service by uploading new S/MIME certificates and private key metadata encrypted by your new service.

About S/MIME

S/MIME is a widely accepted, industry standard protocol for digitally signing and encrypting emails to ensure message integrity and security. Gmail CSE relies on the S/MIME 3.2 IETF standard to send and receive secure MIME data. S/MIME requires email senders and recipients to have their X.509 certificates trusted by Gmail.

Alternatively, you can use S/MIME without the additional layer of encryption and privacy that CSE provides. Use this alternative only if don't need to prevent Google servers from decrypting your data. For details, see Turn on hosted S/MIME for message encryption.

Before you begin

Make sure you've completed the following steps:

Set up your external key service or hardware key encryption.
Add your key service or hardware key encryption to your Admin console.
Assign a key service or hardware key encryption to organizational units or groups.
If you're using multiple key services, make sure they're assigned to the appropriate organizational units or configuration groups.
Connect Google Workspace to your identity provider (IdP).

Set up the Gmail API

Step 1: Enable the Gmail API

Create a new GCP project. For details, see Creating and managing projects.
Note the project ID: You'll use it to grant the API domain-wide access.
Go the Google API Console and enable the Gmail API for the new project. For details, see Enabling an API in your Google Cloud project.

Step 2: Create a service account

In the Google Cloud console, go to the Service accounts page and create a service account. For details, see Create and manage service accounts.
Create a service account private key, and save the key to a JSON file on to your local system, such as svc_acct_creds.json. This file contains the credentials you'll use when setting up Gmail for users. For details, see Create and manage service account keys.

Step 3: Grant the Gmail API domain-wide access

For this step, you'll use the service account you created to give the Gmail API edit access to all your users.

Follow the instructions for Control API access with domain-wide delegation.
Enter the following when prompted:
Client ID: Client ID of the service account created in Step 2 above.

OAuth scope: gmail.settings.basic

Set up Gmail CSE for users

After you've set up Gmail API, you can set up Gmail CSE for your users.

Step 1: Turn on Gmail CSE for your users

Turn on CSE for Gmail for the organizational units or groups. For details, see Turn client-side encryption on or off.

Step 2: Prepare S/MIME certificates and private key metadata

Using a certificate authority (CA), generate an S/MIME certificate for each user who will use Gmail CSE to either send or receive emails. You can do either of the following:
- Use a CA root certificate trusted by Google: For a list of root certificates, see CA certificates trusted by Gmail for S/MIME.
- Use a CA that's not trusted by Google: For example, to use your own CA, you can add its root certificate in the Admin console. For details, see Manage trusted certificates for S/MIME.
  Note: If you use a CA that's not trusted by Google, and users will send client-side encrypted emails outside your organization, the receiver must also trust the CA.
Encrypt, or "wrap," the S/MIME private keys' metadata using your key service. Follow the instructions in your service provider’s documentation.
If you're using hardware key encryption—Make sure you skip this step and don't wrap private key metadata for any users who will use hardware key encryption. In this case, wrapping the metadata isn't needed because users' private keys for Gmail reside on their smart cards. Requires having the Assured Controls add-on.

Step 3: Upload users' S/MIME certificates and private key metadata to Gmail

You need to use the Gmail API to upload each user’s public key S/MIME certificate chain and private key metadata to Gmail and set them as the preferred keys for the users by creating an identity. For authentication, use the service account private key file you downloaded when setting up the Gmail API.

For each user:

Create a keypair, which uploads the certificate chain and private key metadata.
Using the keypair, create a CSE identity that's authorized to send email from the user's account.

To complete these steps, use a script that interfaces with the Gmail API. You can do either of the following:

Write your own script.
Use the Python sample script that Google provides. For instructions, see Use Google's Python script to upload users' certificates and wrapped keys to Gmail below.
Note: This script applies only for users who'll use a key service to encrypt Gmail content. For any users who will use hardware key encryption, you'll need to create a different script to upload their unwrapped private key metadata.

After you upload the certificates, it can take up to 24 hours for them to be available in Gmail, although it usually happens much faster.

(Optional) Use Google's Python sample script to upload users' certificates and wrapped private keys to Gmail

To complete Step 3 above, you can use the Python script that Google provides instead of writing your own script.

Download the script

Download the Python script package (.zip) to your computer (Mac, Linux, or Windows), and extract the files into your working directory.

Create a virtual environment and install modules

Using a command line from your working directory, enter the following commands:

python3 -m venv cli_env

            source cli_env/bin/activate

            pip install -r requirements.txt

Invoke the script

python cse_cmd.py -h

Upload user's certificates and keys

Step 1: Create a directory for storing all wrapped private keys

For example, you might create the directory $root/wrapped_keys.
The filename for each wrapped private key must be the user's full email address with the .wrap extension. For example: $root/wrapped_keys/user1@example.com.wrap
Make sure the wrapped private key file has a JSON object with two required fields:

{

                  'kacls_url': 'url of the key service configured in the Admin console',

                  'wrapped_private_key': 'wrapped private key bytes'

                }

Step 2: Create a directory for storing all certificates

Certificates need to be in the P7 PEM format, so, you might create the directory $root/p7pem_certs.
Make sure the certificate file contains the full chain to the root certificate authority (CA).
The filename for each certificate must be the user's full email address with the .p7pem extension. For example: $root/p7pem_certs/user1@example.com.p7pem

If you have a P7B file: You can use the following openssl comment to convert it to the P7 PEM format:

openssl pkcs7 -inform DER -in {old_name.p7b} -outform PEM -out {new_name.p7pem}

Step 3: Upload users' key pairs and identities

For this step, you'll need the JSON file containing the credentials for the service account, which you saved to your computer in Step 2: Create a service account above.

The easiest way to upload users' key pairs and identities is to run the insert command. Note that each command must have an argument—for example:

python cse_cmd.py insert

                  --creds $root/svc_acct_creds.json

                  --inkeydir $root/wrapped_keys

                  --incertdir $root/p7pem_certs

Alternatively, you can do the following for each user:

Run insert_keypair, and note the keypair ID.
Run insert_identity using that keypair ID.

You can also get the keypair ID by running list_keypair command.

Step 4: Verify users have CSE key pairs and identities

Make sure users have valid key pairs and identities in Gmail by running the following commands for each user:

list_keypair

list_identity

To switch to another key service for Gmail CSE

If you want to switch to a different key service for Gmail CSE, repeat steps 2 and 3 under Set up Gmail CSE for users above, using your new key service to wrap the private keys.

Note: Uploading new certificates for users doesn't migrate content to the new key service. However, users can continue to access emails encrypted with the previous certificates and private key metadata wrapped by the old key service.

Was this helpful?

How can we improve it?