Gmail only: Upload encryption keys for client-side encryption
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.
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.
Perform the following tasks to set up the Gmail API:
- Enable the Gmail API.
- Create a domain-wide service account.
- Grant the Gmail API domain-wide access.
Perform the following steps to enable the Gmail API:
Create a new GCP project. For details, go to Creating and managing projects.
You use the project ID to grant the API domain-wide access.
Go to 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.
Perform the following steps to 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 use when setting up Gmail for users. For details, go to Create and manage service account keys.
This step uses the service account you created to give the Gmail API domain-wide 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 the preceding Step 2.
- OAuth scopes: Paste the following scopes into a separate field:
- https://www.googleapis.com/auth/gmail.settings.basic
- https://www.googleapis.com/auth/gmail.settings.sharing
- https://www.googleapis.com/auth/gmail.readonly
Turn on CSE for Gmail for the organizational units or groups. For details, go to Turn client-side encryption on or off.
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.
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 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.
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:
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:
- A CA root certificate trusted by Google: For a list of root certificates, go to CA certificates trusted by Gmail for S/MIME.
- 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 to Manage trusted certificates for S/MIME.
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.
Perform the following step to obtain the certificate with CAs in PKCS7 PEM format:
On a computer that has OpenSSL installed, run the following command in a terminal:
Perform the following step to get the private key in encrypted PKCS8 format with a password:
On a computer that has OpenSSL installed, run the following command in a terminal:
Use your key service (such as ) to encrypt or wrap the S/MIME private key metadata.
Perform the following steps to upload PKCS8 key through the web dashboard:
Go to the web dashboard in a browser.
Log into the by using the default Admin identities (Admin1 and Admin2).
Select the Google Workspace CSE (Client-side Encryption) service from the list of deployed services on the Service Management page.
Go to the Users view for the service and select the mail icon next to the user for whom you're wrapping the PKCS #8 private key.
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.
sends the wrapped PKCS #8 private key to your browser. Download the file when prompted.
Open the wrapped PKCS #8 private key file in a text editor and copy (or preferably cut) the encrypted key blob to your clipboard.
Open a new file in the text editor. Then, copy and paste the following JSON:
First, change cryptohub-demo.com to the actual domain of your . Then, paste the encrypted key blob into the wrapped_private_key value and save the file with the name [email protected].
Use the Gmail API 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 for authentication and Google's Python script.
Prepare the keys directory and copy the encrypted keys.
Upload the certificate chain and private key metadata by using the Gmail API call keypairs.create.
Enable the keypair for the user's primary email address by using the Gmail API call identities.create.
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.
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 [email protected]) and one or more aliases (such as [email protected]), you should:
- Enroll the user in by using their primary email address
- Configure authentication to the IdP using the primary email username (such as tuser)
- 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.
Perform the following steps to configure Gmail for encrypted emails:
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.
You can track which users have been provisioned S/MIME for Google CSE in the using the Users menu for the service.
Go to Deployed Services > Google Workspace CSE (Client-side Encryption).
In the management menu, select [ Users ].
In the list of users, users who have been provisioned S/MIME have an expiration date listed under S/MIME Expiration.
You can use the 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:
Go to Deployed Services > Google Workspace CSE (Client-side Encryption).
In the management menu, select [ Users ].
For a user provisioned S/MIME, select the X icon for G-mail Key Remove for the user.