How to Easily Add Gmail Certificates to Java Truststore on Windows: A Step-by-Step Guide

Background

It is often a time consuming and cumbersome task to consolidate the relevant financial documents recieved during the course of the year. Whether it be for small businesses, large businesses, personal accounting, or tax purposes. I recently started a small project to assist with the problem of consolidating these documents throughout the year.

The project aims to develop an application that automates the extraction and management of important documents received via email, including financial, tax, insurance, and business-related documents. Since the documents can be in various styles and formats, AI is used to extract structured data to persist to a database.

The system monitors my email address, extracts key details from relevant documents, summarizes them into structured database entries, and stores the documents in an object storage solution like Minio or AWS S3.

The next part of the project aims to incorporate a web UI to view summaries, upcoming payment dates, and download all documents.

The first part of this project involved getting an email client running to monitor my emails. I chose to go with Kotlin for this part of the project. Since we are using a Java Virtual Machine (JVM) based language, I decided to go with the old and trusted Javax mail API for email related operations.

The first issue I encountered was that the Java truststore in my Java Runtime Envirnment (JRE)/Java Development Kit (JDK) did not have the necessary certificate from Google to be able to call the IMAP API. The rest of this post explains how I imported the certificates for Gmail into the Java trustore for the JRE for the email monitoring component.

Prerequisites

I am developing on a Windows machine. The rest of this guide assumes you are using a similar set up. You will need Git bash or WSL to execute some of the following steps but they are optional (we use the AWK command line utility for automatic certificate extraction but you can also use any text editor that your operating system provides). AWK is available in Git bash for Windows. You can find Git bash here.

Obtaining and extracting the certificates

Overview

In this section we are going to download the Gmail IMAP certificate chain, extract the relevant certificates, save the certificates from the chain in their respective files, and finally we’ll verify the extracted certificates using Openssl to ensure their are no errors. A troubleshooting section at the end addresses common errors with extracting the certificates from the certificate chains.

Steps

Firstly we need to download the certificate chain from the certificate authority. This command captures all certificates in the chain into a file named cert_chain.pem.

openssl s_client -connect imap.gmail.com:993 -showcerts > cert_chain.pem

Next we are going to manually verify the contents of the certificate chain. Open cert_chain.pem with a text editor to ensure it contains the certificates in the following format:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Ensure there are no extra characters or lines outside these delimiters. Once we have validated the format of the certificate chain, we then have two options for extracting the certificates.

  1. Use AWK to extract certificates (using Git bash or WSL).
  2. Manually extract the certificates.

Option 1: Use awk to Extract Certificates

Extract the First Certificate (Server Certificate):

awk '/-----BEGIN CERTIFICATE-----/{i++}i==1' cert_chain.pem > server_cert.pem

Extract the Second Certificate (Intermediate Certificate):

awk '/-----BEGIN CERTIFICATE-----/{i++}i==2' cert_chain.pem > intermediate_cert.pem

This will create two certificate files named server_cert.pem and intermmediate_cert.pem that contain the individual certificates from the certificate chain.

Option 2: Manually Split the Certificates

If awk doesn’t work as expected, you can manually split the certificates by copying and pasting the relevant sections from cert_chain.pem into new files. Open cert_chain.pem in a text editor of your choice.

nano cert_chain.pem

Copy everything from the first -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- and paste it into a new file called server_cert.pem. Similarly, copy everything from the second -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- (after the server certificate) and paste it into a new file called intermediate_cert.pem. After extracting the certificates into their respective files, verify each certificate file to ensure they are correctly formatted:

openssl x509 -in server_cert.pem -text -noout
openssl x509 -in intermediate_cert.pem -text -noout

If the certificates are correctly extracted, these commands will display detailed information about each certificate.

Troubleshooting

  • Make sure there are no extra characters or lines in the certificate files. The delimiters should be exactly as shown (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----).
  • Ensure the files are readable and have the correct format. Sometimes, file format issues can cause problems.

By carefully following these steps, you should be able to correctly extract and save the certificates needed for your Java keystore.

Importing the extracted certificates to the truststore

Overview

In this section we will import the certificates that we extracted in the previous section into the trustore of the JRE environment used to run the application.

Steps

To import the extracted certificates into the Java truststore located in C:\Program Files\Java\jdk-18.0.1.1\, first open the command prompt as administrator.

  • Search for ‘cmd ‘in the Start menu.
  • Right-click on “Command Prompt” and select “Run as administrator” to ensure you have the necessary permissions.

Next we need to locate the trustore file. The truststore file is typically named cacerts and is located in the following directory on Windows machines. This will depend on where you installed the JRE or JDK version that you are using for your project.

C:\Program Files\Java\jdk-<version>\lib\security\cacerts

Next we will import the certificates using keytool. Use the keytool utility to import each certificate into the truststore. Replace the paths and aliases with your actual certificate file paths and desired aliases. Use the following commands to import the certificates.

keytool -import -alias server-cert -file C:\path\to\server_cert.pem -keystore "C:\Program Files\Java\jdk-18.0.1.1\lib\security\cacerts" -storepass changeit
keytool -import -alias intermediate-cert -file C:\path\to\intermediate_cert.pem -keystore "C:\Program Files\Java\jdk-18.0.1.1\lib\security\cacerts" -storepass changeit

Notes:

  • Aliases: Use descriptive aliases (e.g., server-cert and intermediate-cert) to easily identify the certificates.
  • Store Password: The default password for the cacerts truststore is changeit. If your truststore uses a different password, replace changeit with the actual password.
    File Paths: Ensure that you provide the correct absolute paths to your .pem files.

Finally we can verify the imported certificates. After importing the certificates, use the following command to verify that the certificates were added correctly.

keytool -list -v -keystore "C:\Program Files\Java\jdk-18.0.1.1\lib\security\cacerts" -storepass changeit

This command lists all the certificates in the truststore, and you should see the aliases server-cert and intermediate-cert with their respective details.

Conclusion

By following these steps, you’ll be able to import the extracted certificates into your Java truststore and ensure that your Java applications can trust the SSL connections. Ensure you are using the correct JRE/JDK where you imported the certificates into the truststore for your project.

Leave a Reply

Your email address will not be published. Required fields are marked *