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 an 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 email messages 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.

Note: 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 with CSE. For details, go to Turn on hosted S/MIME for message encryption.

Before you begin

Make sure you've completed the following steps:

Choose a key service.
Connect to your identity provider (IdP).
Set up your external key service or hardware key encryption.
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.

Set up the Gmail API

Note: Use of the APIs requires programming knowledge.

Expand section | Collapse all

Step 1: Enable the Gmail API

Create a new GCP project. For details, go to 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, go to Enabling an API in your Google Cloud project.

Step 2: Create a domain-wide service account

In the Google Cloud console, go to the Service accounts page and create a domain-wide service account. For details, go to 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, go to 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 scopes: gmail.settings.readonly and either gmail.settings.basic or gmail.settings.sharing

Turn on Gmail CSE for users

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

Note: For organizational units, you can set all email (compose, reply, and forward) to be encrypted by default. User can still turn off encryption if needed. Requires having the Assured Controls or Assured Controls Plus add-on.

Set up CSE S/MIME certificates for users

After you've set up Gmail API and turned on Gmail CSE for users in the Admin console, you can set up CSE S/MIME certificates and private key metadata for your users.

Expand section | Collapse all

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

For each user who will use Gmail CSE to either send or receive email:

Using a certificate authority (CA), generate an S/MIME public/private key pair with a certificate chain. The S/MIME leaf certificate must include the user’s primary Gmail address as a subject name or SAN extension subject.

You can do either of the following:

Use a CA root certificate trusted by Google: For a list of root certificates, go to 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, go to 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 email outside your organization, the receiver must also trust the CA.

Step 2: Wrap certificates and private key metadata

Use your key service to encrypt, or "wrap," the S/MIME private keys' metadata. Contact your key service to do this or follow the instructions they provide.

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 or Assured Controls Plus add-on.

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

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.

Compete the following steps for each user, using the private key file you downloaded when creating a domain-wide service account for authentication:

Upload the certificate chain and private key metadata, using the Gmail API call keypairs.create.
Enable the keypair for the user's primary email address, using the Gmail API call identities.create.
The identities.create call requires the key pair ID that's returned in the response body of the keypairs.create call.

Note: Enabling the key pair for a user's email address:
- Creates a CSE identity that's authorized to send email from the user's account.
- Configures Gmail to use the private key metadata to sign outgoing CSE mail.
- Publishes the certificate to a shared domain-wide repository so other CSE users in your organization can encrypt messages sent to this user.

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, go to 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.

Note: This script asks for the 3 scopes you can use to grant the Gmail API domain-wide accesss (listed earlier on this page): gmail.settings.readonly, gmail.settings.basic, and gmail.settings.sharing. To use the script, you can either enable all three scopes or remove the scope you're not using from the 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 email encrypted with the previous certificates and private key metadata wrapped by the old key service.

Migrate messages to Gmail as client-side encrypted email

Now that Gmail CSE is set up, you can optionally import messages. For details, see Migrate messages to Gmail as client-side encrypted email.

Was this helpful?

How can we improve it?