Gmail only: Upload encryption keys for client-side encryption

For this step, you'll use the service account you created to give the Gmail API 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 Step 2 above.

   OAuth scopes: gmail.settings.readonly and either gmail.settings.basic or gmail.settings.sharing 

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:

1. Upload the certificate chain and private key metadata, using the Gmail API call keypairs.create.
2. 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. 

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:

Invoke the script

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:

  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:

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:

Alternatively, you can do the following for each user:

1. Run insert_keypair, and note the keypair ID.
2. 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