About
This document will walk you through the configuration of CSE for Gmail. This guide will focus on the wrapping of your private key metadata, and also includes instructions for uploading your wrapped S/MIME certificates for each of your organizations users leveraging CSE for Gmail.
Assumptions:
- Virtru Private Keystore for Google CSE is configured within your environment
- You have administrative Privileges in Google Workspace to make configuration changes
- Ability to request S/MIME certificates on behalf of your users
Key Steps
- Acquire S/MIME Certificates for your CSE User(s)
- Wrap key(s) in CSE and format JSON for upload
- Create service account with proper scopes
- Configure Python Client
- Allow GCP project access to use Google’s upload Python client
- Upload user certs and wrapped keys to Google
- Upload CA root certificate to Google S/MIME
Acquire S/MIME Certificates for your CSE User(s)
- Identify which users in your organization will be using CSE for Gmail, and request an S/MIME certificate for each user. Ensure the S/MIME certificate includes the user’s primary Gmail address as a subject name or SAN extension subject. More details surrounding CA's supported by Google can be found here: https://support.google.com/a/answer/13069736
Wrap key(s) in CSE and format JSON for upload
- Log in to your CSE Server
- Copy your user's private key (ex. admin@domain.com.key) to your server running CSE and place it in a new directory called ‘wrapped_private_keys’
- Navigate to the directory containing your key(s)
- Run the following command, and use the relevant directories and kacls URL for your configuration:
CSE Version 5.4.0 or laterdocker run --env-file /var/virtru/cse/cse.env --mount type=bind,source=/var/virtru/cse/secrets.json,target=/app/cse/secrets.json --mount type=bind,source=/var/virtru/cse/private-keys,target=/app/private-keys --mount type=bind,source=/var/virtru/cse/wrapped-private-keys,target=/app/wrapped-private-keys -p 443:9000 <containerID> wrap-private-keys --private_keys_path="/app/private-keys" --kacls_url="https://your.cseserver.domain.com" --wrapped_private_keys_path="/app/wrapped-private-keys"
This command should output the following for each of the keys you are wrapping:
{
"kacls_url": "https://your.cseserver.domain.com",
"wrapped_private_key": "base64 encoded encrypted RSA key"
}
CSE Version <= v5.3.1
sudo docker exec <container-id> /bin/sh -c "node commands/wrap-private-key.js --privateKey=\"$(cat admin\@domaincom.key)\";"
This command should output the following:
{
'wrapped_private_key': 'base64 encoded encrypted RSA key'
}
Copy this key back to your S/MIME folder and move the wrapped key to the wrapped_keys directory.
Update your wrapped key file to the below format:
{
"kacls_url": "https://your.cseserver.domain.com",
"wrapped_private_key": "base64 encoded encrypted RSA key"
}
Create Service Account with proper scopes
In a GCP project, create a service account. The default service account access to the project and user access to the service account is fine. After creating your account, in the details section, click Show Advanced Settings, and click the link under Domain-wide Delegation that will take you to your Google Workspace Admin Console. Once there, go to Security > API Controls, and click the link at the bottom to Manage Domain Wide Delegation, then follow these steps:
- Add new API Client
- Copy the Client ID for your service account from GCP (Unique ID on the service account details page)
- Add these 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'
- Click Authorize
Next, create a key for your service account in GCP. Download the key as JSON, and move the file to your S/MIME directory. Additional details found in this Google Document: https://cloud.google.com/iam/docs/keys-create-delete
Configure Python Client
Using the provided Python client located within this article, under the optional drop down, make sure cse_cmd.py and requirements.txt are in your S/MIME directory, and run the following commands:
python3 -m venv cli_env
source cli_env/bin/activate
pip install -r requirements.txt
Now, make sure your root directory for S/MIME has the cse_cmd.py file, and that you’ve downloaded the service account from your GCP project.
Upload User Certs and Wrapped Keys to Google
Next, you should be able to run the Python client to upload any wrapped keys and user certs to your Google config. To do this, follow these steps:
- Ensure all certificates are in pkcs7 format with a p7pem extension, with the name of the file being the user that cert belongs to (ex: admin@domain.com.p7pem)
- Ensure all wrapped keys have a .wrap extension, with the name of the file being the user the key belongs to (ex: admin@domain.com.wrap)
- Ensure the service account private key, and your certificate materials are in the same directory as you are running your python venv out of
- Run the command below
python cse_cmd.py insert --creds <service-account-key>.json --inkeydir wrapped_private_keys --incertdir p7pem_certs
You should see an output with this format for each key you have in your keys directory:
Processing user:admin@domain.com
{'keyPairId': 'SomeKeyPairID', 'kaclsUri': 'https://your.cseserver.domain.com', 'pem': '-----BEGIN CERTIFICATE-----\nYOURCERTIFICATE\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nANOTHERCERTIFICATE\n-----END CERTIFICATE-----\n', 'subjectEmailAddresses': ['admin@domain.com]}
{'emailAddress': 'admin@domain.com', 'primaryKeyPairId': 'SomeKeyPairID'}
Upload Root CA Certificate to Google S/MIME settings
Navigate to https://admin.google.com/ac/apps/gmail/usersettings, and under S/MIME, check the box to enable S/MIME encryption and to allow users to upload their own certificates. Add a certificate under “Accept these additional root certificates for specific domains”, and add the ca.crt file you used when generating your user certificate and set the address list to include your domain.