Over a million developers have joined DZone.

2-Way SSL with Java: The Keystore Strikes Back - Part 1

DZone's Guide to

2-Way SSL with Java: The Keystore Strikes Back - Part 1

If you start off trying to get to grips with the in-built Java Secure Sockets Extension you're gonna be stunned by the complexity of it all.

· Java Zone ·
Free Resource

Download Microservices for Java Developers: A hands-on introduction to frameworks and containers. Brought to you in partnership with Red Hat.

You'd think with how prevalent SSL/TLS on the web that SSL with Java is easy, well it's not. In addition to having to get to grips with understanding how private/public key, certificates work there's all the networking that goes on in Java.

If you start off trying to get to grips with the in-built Java Secure Sockets Extension you're gonna be stunned by the complexity of it all.

Clear as mud eh? The JSSE guide alone is 73 pages long - but I hate to say that its REALLY a must read. Print it out (double-sided to save some trees) grab a Venti decaff or two and wrestle the information into your brain.

Thankfully Jakarta Commons HTTP client makes it relatively easy code-wise (Side Note: Why the heck does HTTP Components v4.0 seem so much more complicated than v3.0? The v4 docs seems much less clear!). For example:

HttpClient httpclient = new HttpClient();GetMethod httpget = new GetMethod("https://www.bob.com/");try {httpclient.executeMethod(httpget);System.out.println(httpget.getStatusLine());}finally {httpget.releaseConnection();}  

In any event it's pretty straightforward code-wise with HTTP Client until you have to start to get to grips with three funky things - they are

1) the keystore
2) the truststore
3) keytool to access both


Lets start off with a truststore. In a normal 1-Way SSL situation, say on a browser, you need your bank's server to authenticate itself to assure you that you are hitting the REAL bank server and not some spoofed site. So in the 1-Way SSL case the bank server sends your browser a certificate signed by a CA(Certificate Authority) then your browser compares that CA signature against an in-built list of CAs. In a similar way your truststore is your secure store of trusted CA entries or self-signed certs provided from third parties you trust. So essentially the truststore contains the certificates you use to authenticate other servers / processes. Every Java install comes with it's own truststore located in $JAVA_HOME/lib/security/cacerts


A keystore is, as you can imagine, is a secure store for keys used in the SSL protocol. Essentially it's where you will put private keys and their associated certificates used to authenticate YOU as client to a server. Typically in a normal web browser transaction you use 1-Way SSL to authenticate the server then you use a login/password combo to authenticate you. Well in B2B systems you can use 2-Way SSL where client and server authenticate each other - and this is where the keystore is critical to authenticate your Java program, the client, to the server.

Typically for client authenticate you create either a self-signed or you purchase a CA signed cert. You store your private key and public cert in the keystore and provide your B2B partner with the self-signed cert - or in the case of a CA-signed cert typically your partner's truststore will trust that CA and you are good to go.


keytool is the command line tool to maintain these two beasts. And let's just say it's not easy to use keytool. It's like snowboarding - its good when you're used to it but getting started with keytool you're gonna spend a lot of time on your ass or face first! If you're just getting started with keystores and truststores I strongly recommend using Portecle - an open source GUI tool which makes keytool obsolete and should really ship with Java someday.

Then you have to tell java where they keystore and truststore are and the passwords to these stores. Well you can do that with System properties e.g.


If standards are good, more is better right?

Getting tired yet? Well this is gonna put you over the edge . . . . when you get keys and certs from your B2B partners how many types of files do you think there are - two? three? four? Let's list the ones I've had to deal with lately.

  1. pfx
  2. pem
  3. p12
  4. cer
  5. crt
  6. der

It's madness! If you want a good description overview of the file formats then this link is a good place to start. This is when openssl becomes your friend when you need to convert from different file formats into formats compatible with keytool - oh and good luck finding documentation on which file formats keytool takes!

In any event so far things are tough but not insurmountable - well so I thought until two B2B partners decided to provide me each with a key for my keystore to authenticate me. A key of the same type (RSA), signed by the same CA. Then all hell broke loose - cos Java don't support that without some major surgery . . . . and that's the topic of Part II.

From http://softarc.blogspot.com/2011/03/2-way-ssl-with-java-keystore-strikes.html

Download Building Reactive Microservices in Java: Asynchronous and Event-Based Application Design. Brought to you in partnership with Red Hat


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}