Monday, March 5, 2012

How to add or list certificates from keystore or trustStore in Java - Keytool Example

How to add certificates on keystore in Java is primary questions when you start working on SSL connection and simple answer is keytool utility in Java is used to add or list Certificates into keystore. SSL is industry standard for secure communication between two parties e.g. client and server. SSL offers two benefits, it encrypts data transferred between client and server to make it hard for someone to access and understand in between and SSL also verify identity of two parties in communication and certificates are used for that purpose. SSL Setup in Java comes during various process e.g. Setting up SSL on tomcat, configuring messaging over SSL or JDBC over SSL are some examples of task where you need to deal with keyStore, certificates and trustStores. for those who are not aware of what is a keystore in Java and what is certificates, we will see brief introduction in next section.

Basics of SSL Certificates and Keystore in Java

How to add list certificates from keystore and trustStore in Java using keytoolWhen we access a secure site which uses SSL for providing identity and encryption, it provides a certificates which was verified by a trusted third party sites like verisign, godaddy or thwate. by using certificates browser or java clients knows that they talking to the correct site (who it claims to be) and not on redirected proxy site. this step is pretty transparent if you access websites using browser because if certificate is not on browser's trusted store it will ask you to add that certificate and it will be subsequently added, But when you access a secure site using Java program, this step of certificate hand shaking is not transparent to user and certificates are verified form JRE's trustStore. This trustStore is located on JDK Installation directory referred by JAVA_HOME  e.g. JAVA_HOME/jre/lib/security and commonly named as "cacerts".If certificate provided by secure site is present on JRE's trustStore SSL connection would be established but if certificate is not there than Java will throw exception and to solve that you need to add that certiificate into trustStore. keyStore and trustStore is often used interchangeably and same file can act as keystore as well as trustStore it just matter of pointing javax.net.ssl.keyStore and javax.net.ssl.trustStore properties to that file but there is slightly difference between keystore and trustStore. keyStore is used to store individual identity or certificate while trustStore is used to store other parties certificates signed by CA.
 

How to add ,remove and list certiifcates from Java keystore

In this article we will see how to add ,remove and list certiifcates from Java keystore using keytool utility.
keytool is binary located inside JAVA_HOME/jre/lib/security folder and used for adding, removing and listing
certificates. here is step by step example of adding certificates in Java:

Example of listing certificates form Java Keystore:

Before adding new certificates in keystore or truststore its good to see, count and verify already installed certificates. run following keytool command to get a list of certififcates from keystore:

javin@localhost:C/Program Files/Java/jdk1.6.0_26/jre/lib/security keytool -list -keystore cacerts
Enter keystore password:  changeit

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 76 entries

digicertassuredidrootca, 07/01/2008, trustedCertEntry,
Certificate fingerprint (MD5): 87:CE:0B:7B:2A:0E:49:00:E1:58:71:9B:37:A8:93:72
trustcenterclass2caii, 07/01/2008, trustedCertEntry,
Certificate fingerprint (MD5): CE:78:33:5C:59:78:01:6E:18:EA:B9:36:A0:B9:2E:23


You see currently keystore "cacerts" holds 76 certificates.

Example of adding Certificate on Java KeyStore:

Now let's see example of adding certificates into keytstore in Java:

1. Get Certificate: easier way is point your browser to that url and when certificate is presented save it on your
local folder or directory say in C:/certificates/test.cer

2. Now go to Security folder of your JRE installation directory. id you have JDK installed than it would be
something like C:/Program Files/Java//jdk1.6.0_20/jre/lib/security

3 Execute following keytool command to insert certificate into keystore

keytool -import -keystore cacerts -file test.cer

Now this will print details about certificate and ask you for confirmation of adding certificates:

Trust this certificate? [no]:  y
Certificate was added to keystore

if you approve it by typing "y" certificate will be added into keystore.

Trust this certificate? [no]:  n
Certificate was not added to keystore

if you decline it by typing "n" certificate will not be added into keystore.

if you cannot access secure URL using browser than you can use InstallCert by which you can add certificate into
keystore by program. for detailed example see last section of LDAP authentication with SSL in Java and Spring security. I have provided detailed steps to use InstallCert.java tool.

Important point about SSL, KeyStore and keyTool in Java

1. Certificates are required to access secure sites using SSL protocol or making secure connection from client to server.
2. JRE stores certificates inside keystore named as "cacerts" in folder C:/Program Files/Java//jdk1.6.0_20/jre/lib/security.
3. Common password of keystore is "Changeit"
4. Keytool is used to access keystore in Java and by using keytool you can list, add certificates from keystore.
5. if you are implementing SSL connection on Server side say Tomcat you need both keyStore and trustStore, both can be same file though. keyStore will be used to store server certificate which server will present to client on SSL connection.

That’s all on how to add and list certificates from keyStore or trustStore in java. Keytool utility which comes with JDK installation will help you to create alias, list certificates etc.

Other Java tutorials you may like:

7 comments :

Anonymous said...

Can you also let us know how to create keystore in Java, I mean what if I want to create a new keystore or copying data from one keyStore to another ? I am looking for exact command using keytool, please help.

Anonymous said...

I am getting this error while connecting to my Server using SSL in Java "javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed" Its says requested certificate not found. I am using self signed certificate created using keytool and I have imported that certificate into keystore. Is there any other way to install certificate ? do I need to install certificate on server side or only on client side ?

Pankaj said...

Instead of adding certificates using keyword tool, I prefer to use InstallCert.java utility. If you are adding certificates from website or url like LDAP URL, its best to use InstallCert.java. here is the command I use, just make sure to run this command from JRE/lib/security directory:

java -cp . InstallCert hostname:port

Johnny Cheng said...

@Anonymous, There could be multiple reason of error javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed e.g.

1)Your trustStore may not contain certificates sent by Server for authentication.

2) You might not have provided trustStore using system property -Djavax.net.ssl.trustStore=, if you don't provide an explicit trustStore than default trustStore which is jss2certs or cacerts and located in JRE/lib/security directory is used, which might not contain certificates sent by Server.

3) If your SSL Server is using Client authentication than you need to provide keyStore as well with System Property
-Djavax.net.ssl.keyStoreType=
-Djavax.net.ssl.keyStore=
-Djavax.net.ssl.keyStorePassword =< keystore password>

because on client side authentication SSL clients sends certificates corresponding to its public key to Server.

What you can do :
1) Check if you are using client side authentication or not, if not then you don't need keystore, until you are SSL Server.

2) See whether you are using an explicit trustStore file or a default trustStore e.g. mytrustStore.jks in your application, make sure that you have Certificates to authenticate server on those trustStore.

Deepak Gaikkars said...

One cal also use GUI based key management utility to create keystore and import certificates on that like IBM IkeyMan tool. Though I personally prefer keytool command which comes with standard Java installation, GUI tools are much easier to use. Another important thing to remember that, you can use same keystore as both trustStore and keyStore in Java which is used for different purposes.

Java Security Programmer said...

Ikeyman is better when you want to create keyStore in Java, it support different kinds of keyStore e.g . JKS keyStore. Also if you want to create personal certificates, you first need to create certificate request and later signed it using A Signing authority e.g. GoDaday or Thwate. By the you can self sign your Certificate as well for development and testing purpose.

Anonymous said...

The default password of java keystore is "changeit", all in lower case.

Post a Comment