Table of Contents
Introduction to the Keytool utility
The keytool utility is a command-line tool included with the Java Development Kit (JDK) that allows users to manage the keystore that contains their keys and certificates. The keystore is a repository of security certificates, either generated by the keytool or imported from other sources, that can be used to authenticate the identity of a Java application or applet. The keytool can be used to generate new keys and certificates, import existing keys and certificates from other sources, export keys, and certificates to other locations, view the contents of the keystore, and manage the entries in the keystore. It is an essential tool for any Java developer working with security in a Java environment.
What is a keystore?
A keystore is a repository of security certificates, either generated by the keytool or imported from other sources, that can be used to authenticate the identity of a Java application or applet. The keystore is a file on the local file system that contains the keys and certificates used by the Java runtime to establish secure connections and verify the identity of applications and applets.
The keystore is managed by the keytool utility, which is included with the Java Development Kit (JDK). The keytool can be used to generate new keys and certificates, import existing keys and certificates from other sources, export keys, and certificates to other locations, view the contents of the keystore, and manage the entries in the keystore.
By default, the keystore is stored in a file called keystore.jks in the user’s home directory. However, the location and name of the keystore file can be specified when using the keytool, allowing you to have multiple keystores if necessary.
Use cases of the keytool utility
The main use cases for the keytool utility are as follows:
Generating new keys and certificates
The keytool can be used to generate new key pairs and certificates that can be used for authentication and secure communication in a Java environment. The keytool can generate keys and certificates using various algorithms and options, allowing you to customize the security of the keys and certificates to meet your specific needs.
Importing existing keys and certificates:
The keytool can be used to import existing keys and certificates from other sources into the keystore, allowing you to use existing keys and certificates in a Java environment. This can be useful if you have keys and certificates from other sources that you want to use in your Java applications or applets.
Exporting keys and certificates
The keytool can be used to export keys and certificates from the keystore to other locations, such as other keystores or files on the local file system. This can be useful if you want to share keys and certificates with other parties or transfer them to another keystore for use in a different Java environment.
Viewing the contents of the keystore
The keytool can be used to view the contents of the keystore, including the entries in the keystore and the details of the keys and certificates. This can be useful for managing and organizing the keys and certificates in the keystore, as well as for troubleshooting any issues that may arise.
Managing keystore entries
The keytool can be used to manage the entries in the keystore, including changing the passwords for keys and certificates, renaming entries, and deleting entries. This can be useful for maintaining the security of the keys and certificates in the keystore and keeping the keystore organized and up-to-date.
Generating new keys and certificates with the keytool
To generate new keys and certificates with the keytool, you can use the keytool -genkey command. This command generates a new key pair (a public key and a private key) and wraps the public key in a certificate, which is stored in the keystore. The keytool -genkey command takes a number of options that allow you to specify the details of the key and certificate, such as the algorithm to use for the key, the validity period for the certificate, and the name and location of the keystore.
Here is an example of how to use the keytool -genkey command to generate a new key pair and certificate:
keytool -genkey -keyalg RSA -keysize 2048 -validity 365 -keystore sitekey.jks
The above command only works if you already have keytool in your path. I’m not going to show you how to add the keytool to path here. However, you can find it inside your JDK folder:
Here is a brief explanation of each argument:
-keyalg: Specifies the algorithm that should be used for the key-keysize: Specifies the length (in bits) of the key-validity: specify the length should this key be valid-keystore: Specify the name and location of the keystore where this key and certificate should be stored.
You can specify an alias for the key when creating it so you can refer to that alias when exporting the key.
View Content of the keystore
To view the content of the keystore, you can run the following command:
keytool -list -keystore sitekey.jks
You need to enter the password of the keystore to view the content. The default keystore of the JDK is changeit. If you create a new keystore, you need to remember the password you set.
Here is the output:
As you can see, there are two entries in the keystore I inspected.
Exporting keys and certificates from the keystore
To export keys and certificates from the keystore, you need:
- The entry’s alias
- The keystore’s password
Then run the following command:
keytool -exportcert -alias desktop_app -file desktop_app.cer -keystore sitekey.jks
Running this command will export a certificate with the alias desktop_app to a file named desktop_app.cer
You can then use this file to import to other keystore.
Import existing keys and certificates into the keystone
To import existing keys into a keystore, you can use the following command:
keytool -importcert -alias imported_desktop_app -file ./desktop_app.cer -keystore another-keystore.jks
The tool will prompt you to enter the keystore password and ask if you trust the certificate.
If you want to import, simply type yes.
Now, you can use the -list command to view the certificate in the keystore:
Import SSL self-signed SSL certificate to the keystore
Often times in development, you need to generate a certificate authority(CA) then certificates from that CA. Since the CA certificate is self-signed, it is not in the keystore and obviously not trusted. The solution is to import the self-signed certificate to the cacert keystore in your JDK.
If you need guide to generate a self-signed CA certificate and SSL certificate, check out this tutorial here
Locate the cacert keystore in JDK
By default, the cacert keystore is located under JDK_HOME/lib/security/cacerts. For example, here is the cacerts keystore loclation in my Mac: /Library/Java/JavaVirtualMachines/jdk-19.jdk/Contents/Home/lib/security/cacerts
Import the CA cert into JDK keystore
If you have multiple JDK installed, you may need to do this on very JDK. Some people complained why they imported the CA cert into their keystore but when running in the JDK, they still got the error saying cert is not trusted (PKIX…)
The problem is the IDE might use a different JDK. You need to import the CA cert into that’s JDK cacerts keystore too.
To import a CA cert to the keystore, simply run this command:
keytool -import -trustcacerts -file /path/to/cacert-file -alias any_alias_is_ok -keystore /path_to_jdk_ca_cert_keystore -storepass your_keystore_pass -noprompt
Here is a real-life example:
keytool -import -trustcacerts -file ./cacert.pem -alias datmt_self_signed -keystore /Library/Java/JavaVirtualMachines/jdk-19.jdk/Contents/Home/lib/security/cacerts --storepass changeit -noprompt
The command may ask for sudo privileges so you may run it with sudo (or on windows, you need to run Command Prompt/PowerShell… with admin’s right)
If I list the certificates in the keystore, I can see the certificates there:
Conclusion
In this post, I’ve introduced you to the keytool utility in Java. As you work with various applications, certificate management is vital so knowing how to work with this utility will be useful.
I build softwares that solve problems. I also love writing/documenting things I learn/want to learn.