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 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:
Create a new GCP project. For details, go to Creating and managing projects.
Note You use the project ID 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.
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 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:
- https://www.googleapis.com/auth/gmail.settings.basic
- https://www.googleapis.com/auth/gmail.settings.sharing
- https://www.googleapis.com/auth/gmail.readonly
Paste each scope into a separate field.
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 a user is automatically generated by the GCSE service, 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 generated above 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's not trusted by Google and users send client-side encrypted emails outside your organization, the receiver must also trust the CA.
On a computer that has OpenSSL installed, run the following command in a terminal:
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.
Go to the web dashboard in a browser.
Log in to the 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 in the following JSO:
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.
Compete the following steps for each user by using 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.
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 CryptoHub 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 do so, follow these steps
Go to Deployed Services > Google Workspace CSE (Client-side Encryption).
In the management menu, select [ Users ].
For a user that has been provisioned S/MIME, select the X icon for G-mail Key Remove for the user.