Skip to main content
To use Google Workspace Client-side encryption (CSE) for Gmail, you must 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 use an encryption key service, you must also encrypt (or wrap) users’ private key metadata by using your key service. At any time, you can switch to a different key service by uploading a new S/MIME certificate 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.

​
Set up the Gmail API

Perform the following tasks to set up the Gmail API:
  1. Enable the Gmail API.
  2. Create a domain-wide service account.
  3. Grant the Gmail API domain-wide access.

​
Enable the Gmail API

Perform the following steps to enable the Gmail API:
1
Create a new GCP project. For details, go to Creating and managing projects (cloud.google.com/resource-manager/docs/creating-managing-projects).
You use the project ID to grant the API domain-wide access.
2
Go to theGoogle API Console and enable the Gmail API for the new project. For details, go to Enabling an API in your Google Cloud project (cloud.google.com/endpoints/docs/openapi/enable-api).

​
Create a service account

Perform the following steps to create a domain-wide service account:
1
In the Google Cloud console, go to theService accountspage and create a domain-wide service account. For details, go toCreate and manage service accounts (cloud.google.com/iam/docs/creating-managing-service-accounts).
2
Create a service account private key, and save the key to a JSON file on your local system, such as svc_acct_creds.json. This file contains the credentials you use when setting up Gmail for users. For details, go toCreate and manage service account keys (cloud.google.com/iam/docs/creating-managing-service-account-keys).

​
Grant the Gmail API access

This step uses the service account you created to give the Gmail API domain-wide edit access to all your users.
1
Follow the instructions for Control API access with domain-wide delegation.
2
Enter the following when prompted:-Client ID: Client ID of the service account created in the preceding Step 2. -OAuth scopes: Paste the following scopes into a separate field:

​
Turn on Gmail CSE for users

Turn on CSE for Gmail for the organizational units or groups. For details, go toTurn client-side encryption on or off ( support.google.com/a/answer/10745596).
For organizational units, you can set all emails (compose, reply, and forward) to be encrypted by default. Users can still turn off encryption if needed. Requires having the Assured Controls add-on (support.google.com/a/answer/13880647).

​
Set up CSE S/MIME certificates for users

After you set up Gmail API and turn on Gmail CSE for users in the Admin console, you can set up CSE S/MIME certificates and private key metadata for your users.
After a new user is fully provisioned on the Google Workspace with the correct permissions for GCSE, they should immediately be able to use the file encryption functionality of GCSE with no further implementation required on the CryptoHub service.When the GCSE service automatically generates a user, if they have the correct licenses in the workspace, their encrypted email (S/MIME) certificates should also automatically be created.The following section details the manual process.

​
Prepare S/MIME certificates and private key metadata

This section applies to users who uses Gmail CSE to either send or receive emails. Using a certificate authority (CA), generate an S/MIME public/private key pair with a certificate chain. The S/MIME leaf/client certificate must include the user’s primary Gmail address as a subject name or SAN extension subject. You can use the following OpenSSL command to generate the S/MIME leaf certificate:
Shell
openssl req -new -newkey rsa:2048 -nodes -keyout mykey.pem -out mycsr.csr
The email should be the CN. No other DN fields are needed.
Next, you must retrieve the leaf/client CSR you generated, signed by either of the following methods:
  1. A CA root certificate trusted by Google: For a list of root certificates, go to CA certificates trusted by Gmail for S/MIME (
support.google.com/a/answer/7448393). 2.A CA not trusted by Google: For example, to use your own CA, you can add its root certificate in the Admin console. For details, go toManage trusted certificates for S/MIME ( support.google.com/a/answer/13297070).
If you use a CA that Google does not trust and users send client-side encrypted emails outside your organization, the receiver must also trust the CA.

​
Obtain the certificate

Perform the following step to obtain the certificate with CAs in PKCS7 PEM format:
1
On a computer that has OpenSSL installed, run the following command in a terminal:
Shell
openssl crl2pkcs7 -nocrl -certfile cert_88231_ca_bundle.crt --certfile cert_88231.crt -out user.p7pem

​
Get the private key

Perform the following step to get the private key in encrypted PKCS8 format with a password:
1
On a computer that has OpenSSL installed, run the following command in a terminal:
Shell
openssl pkcs8 -topk8 -inform PEM -in user.key -outform PEM -out user.p8 -v2 aes-256-cbc

​
Wrap certificates and private key metadata

Use your key service (such as CryptoHub) to encrypt or wrap the S/MIME private key metadata. Perform the following steps to upload PKCS8 key through the CryptoHub web dashboard:
1
Go to the CryptoHub web dashboard in a browser.
2
Log into the CryptoHub by using the default Admin identities (Admin1 and Admin2).
3
Select the Google Workspace CSE (Client-side Encryption) service from the list of deployed services on the Service Managementpage.
4
Go to the Usersview for the service and select the mail icon next to the user for whom you’re wrapping the PKCS #8 private key.
5
In the Wrap Private Key dialog, enter a password to wrap the PKCS #8 private key under, select [ Upload ], and select the file to upload.
6
CryptoHub sends the wrapped PKCS #8 private key to your browser. Download the file when prompted.
7
Open the wrapped PKCS #8 private key file in a text editor and copy (or preferably cut) the encrypted key blob to your clipboard.
8
Open a new file in the text editor. Then, copy and paste the following JSON:
JSON
{
      "kacls_url": "https://cryptohub-demo.com/v0/key-encrypt/client",
      "wrapped_private_key": ""
}
First, change cryptohub-demo.com to the actual domain of your CryptoHub. Then, paste the encrypted key blob into the wrapped_private_key value and save the file with the name demo@futurex.com.wrap.

​
Upload the certificates and key metadata

Use the Gmail API ( developers.google.com/gmail/api/reference/rest) to upload each public key S/MIME certificate chain and private key metadata for each user to Gmail and set them as the preferred keys for the users by creating an identity. To upload the user S/MIME certificates and private key metadata to Gmail, complete the following steps for each user. Use the private key file you downloaded when creating a domain-wide service account ( support.google.com/a/answer/13069736?hl=en&ref_topic=10742486#service) for authentication and Google’s Python script ( support.google.com/a/answer/13069736?hl=en&ref_topic=10742486#script&zippy=%2Coptional-use-googles-python-sample-script-to-upload-users-certificates-and-wrapped-private-keys-to-gmail).
1
Prepare the keys directory and copy the encrypted keys.
Shell
mkdir -p keys
cp user.p7pem ./keys/demo@futurex.com.p7pem
cp user.wrap ./keys/demo@futurex.com.wrap
2
Upload the certificate chain and private key metadata by using the Gmail API operation:keypairs.create (developers.google.com/gmail/api/reference/rest#rest-resource:-v1.users.settings.cse.keypairs).
Shell
python cse_cmd.py insert_keypair --creds projectname-9a4ed8338919.json --inkeydir ./keys --incertdir ./keys
3
Enable the keypair for the user’s primary email address by using the Gmail API operationidentities.create: (developers.google.com/gmail/api/reference/rest#rest-resource:-v1.users.settings.cse.identities).
Shell
python cse_cmd.py insert_identity --creds projectname-9a4ed8338919.json --userid demo@-futurex.com --kpemail demo@futurex.com --kpid ANe1Bmjz20ByAdWIjbHBYUXsS8BF82RxJ1Oa13cGxWT_B0RpXmVHmE8
The identities.create call requires the key pair ID returned in the response body of the keypairs.create call.
Enabling the key pair for a user email address:
  • Creates a CSE identity authorized to send email from the user 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.
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.

​
Supporting email aliases with CSE

The integration now supports email aliases linked to a single Gmail account. This allows users to send and receive encrypted emails using any of their associated email addresses (primary or aliases) while maintaining proper encryption and decryption capabilities. For example, if a user has a primary email address (such as tuser@companyname.com) and one or more aliases (such as test.user@companyname.com), you should:
  1. Enroll the user in CryptoHub by using their primary email address
  2. Configure authentication to the IdP using the primary email username (such as tuser)
  3. When uploading S/MIME certificates, ensure they include both the primary email and all aliases in the subject name or SAN extension
This configuration enables:
  • Users to send encrypted emails from either their primary address or any alias.
  • Recipients to properly decrypt emails regardless of which address (primary or alias) was used to send the message.
  • All encrypted emails to be accessible within the same Gmail account.
When generating S/MIME certificates for users with aliases, make sure to include all associated email addresses in the certificate’s Subject Alternative Name (SAN) field.

​
Configure Gmail

Perform the following steps to configure Gmail for encrypted emails:
1
Compose a new email in Gmail: When writing your email, you can click on the lock icon next to the recipient’s name to choose the level of encryption.
  • Green: Strong encryption, both parties have S/MIME enabled.
  • Gray: The email will be encrypted, but the recipient’s identity isn’t verified.
  • Red: The recipient does not support encryption.

​
Track provisioned users

You can track which users have been provisioned S/MIME for Google CSE in the CryptoHub using the Users menu for the service.
1
Go to Deployed Services> Google Workspace CSE (Client-side Encryption).
2
In the management menu, select [ Users ].
3
In the list of users, users who have been provisioned S/MIME have an expiration datelisted under S/MIME Expiration.

​
Delete a pairing from Google

You can use the CryptoHub to delete the identity/user pairing, which you send to Google by using cURL REST calls. To delete a user’s S/MIME identity/user pairing from Google, follow these steps:
1
Go to Deployed Services> Google Workspace CSE (Client-side Encryption).
2
In the management menu, select** [ Users ]**.
3
For a user-provisioned S/MIME, select the Xicon for G-mail Key Remove for the user.