Thursday, July 8, 2010

How to Create Client/Server Keystores using Java Keytool

Here I have described how to create client/server keystores which can be used to secure Axsi2 webservices and invoke Axis2 secured webservices. i.e. It can be easily used with any WSO2 Product to experience security scenarios.More detailed explanation on creating client/server keystores using openssl including Certificate Authority(CA) Requests, can be found at http://wso2.org/library/174.

Java keytool stores the keys and certificates in a keystore, protected by a keystore password. Further, it protects private key again with another password. A Java keystore contains private-public key pair and multiple trusted certificate entries. All entries in a keystore are referred by aliases. Both private key and self signed public key is referred by one alias while any other trusted certificates are referred by different individual aliases.

As the first step, let's create a keystore for server. In order to do it, execute following command in a terminal. "server" in the following command corresponds to the private key/self signed public key certificate alias in the keystore while "server.jks" is the name of the creating keystore file.
keytool -genkey -alias server -keyalg RSA -keystore server.jks
when you execute the above command it will first prompt you to specify a password which is corresponded to the keystore password. Then it will prompt several questions. You can give answers that you wish. At the end it will ask for a password again, which will be used to secure the generated private key.
Enter keystore password:  
Re-enter new password: 
What is your first and last name?
[Unknown]:  Ruchira Wageesha
What is the name of your organizational unit?
[Unknown]:  Mashup Server
What is the name of your organization?
[Unknown]:  WSO2
What is the name of your City or Locality?
[Unknown]:  Ahangama
What is the name of your State or Province?
[Unknown]:  Southern
What is the two-letter country code for this unit?
[Unknown]:  LK
Is CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK correct?
[no]: yes
Enter key password for 
(RETURN if same as keystore password):
Once you successfully completed this, java keytool will create a file named "server.jks". In the same way, you can create a client keystore named "client.jks" with the alias "client" using following command.
keytool -genkey -alias client -keyalg RSA -keystore client.jks
Now, you have two files named client.jks and server.jks. You can view the content of these keystore files using the following command. Replacess "ruchira" with the keystore password you entered while creating the keystore.
keytool -list -v -keystore server.jks -storepass ruchira
This will list something like this.
Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: server
Creation date: Jul 8, 2010
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Issuer: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Serial number: 4c356225
Valid from: Thu Jul 08 10:59:09 IST 2010 until: Wed Oct 06 10:59:09 IST 2010
Certificate fingerprints:
MD5:  60:0B:48:0D:DB:56:8C:68:8C:2D:94:4A:D6:DA:04:B8
SHA1: A7:CE:57:10:70:87:C1:2C:C0:9D:1D:90:8C:BB:69:B6:66:26:97:13
Signature algorithm name: SHA1withRSA
Version: 3


*******************************************
*******************************************
The next step is, getting server's self signed public key certificate and storing it in client's keystore. And getting and storing client's self signed public key certificate in server's keystore. In order to do that, first we need to export both server and client public key certificates into files. Using the following command, you can export server's public key certificate into server.cert file and client's public key certificate into client.cert file.
keytool -export -file server.cert -keystore server.jks -storepass ruchira -alias server
keytool -export -file client.cert -keystore client.jks -storepass ruchira -alias client
Now you have server.cert and client.cert. You can use following commands to view certificate contents.
keytool -printcert -v -file server.cert
keytool -printcert -v -file client.cert
As the last step, we need to import server.cert into client keystore and client.cert into server keystore. As I mentioned earlier, each entry of a Java Keystore is stored against an alias. So, we need to specify aliases here, which will be used to refer the certificates that we are going to store.
keytool -import -file client.cert -keystore server.jks -storepass ruchira -alias client
Above command will store client's self signed public key certificate(client.cert) in server.jks against the alias "client". So, using "client" alias on server.jks, we can refer client's certificate anytime. Likewise, following command will store server.cert within client.jks against the alias "server".
keytool -import -file server.cert -keystore client.jks -storepass ruchira -alias server
After all, please view the content of both keystore again using following commands.
keytool -list -v -keystore server.jks -storepass ruchira
keytool -list -v -keystore client.jks -storepass ruchira
It will give you something like bellow for server.jks
Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

Alias name: server
Creation date: Jul 8, 2010
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Issuer: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Serial number: 4c3562a0
Valid from: Thu Jul 08 11:01:12 IST 2010 until: Wed Oct 06 11:01:12 IST 2010
Certificate fingerprints:
MD5:  AB:77:72:F1:0D:09:55:E3:B6:D3:DC:A6:4D:D4:39:36
SHA1: D7:C1:60:5C:7E:34:40:A9:0B:E4:2C:65:6C:E0:79:7C:EE:37:A7:19
Signature algorithm name: SHA1withRSA
Version: 3


*******************************************
*******************************************


Alias name: client
Creation date: Jul 8, 2010
Entry type: trustedCertEntry

Owner: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Issuer: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Serial number: 4c356225
Valid from: Thu Jul 08 10:59:09 IST 2010 until: Wed Oct 06 10:59:09 IST 2010
Certificate fingerprints:
MD5:  60:0B:48:0D:DB:56:8C:68:8C:2D:94:4A:D6:DA:04:B8
SHA1: A7:CE:57:10:70:87:C1:2C:C0:9D:1D:90:8C:BB:69:B6:66:26:97:13
Signature algorithm name: SHA1withRSA
Version: 3


*******************************************
*******************************************

something like below for client.jks
Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

Alias name: server
Creation date: Jul 8, 2010
Entry type: trustedCertEntry

Owner: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Issuer: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Serial number: 4c3562a0
Valid from: Thu Jul 08 11:01:12 IST 2010 until: Wed Oct 06 11:01:12 IST 2010
Certificate fingerprints:
MD5:  AB:77:72:F1:0D:09:55:E3:B6:D3:DC:A6:4D:D4:39:36
SHA1: D7:C1:60:5C:7E:34:40:A9:0B:E4:2C:65:6C:E0:79:7C:EE:37:A7:19
Signature algorithm name: SHA1withRSA
Version: 3


*******************************************
*******************************************


Alias name: client
Creation date: Jul 8, 2010
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Issuer: CN=Ruchira Wageesha, OU=Mashup Server, O=WSO2, L=Ahangama, ST=Southern, C=LK
Serial number: 4c356225
Valid from: Thu Jul 08 10:59:09 IST 2010 until: Wed Oct 06 10:59:09 IST 2010
Certificate fingerprints:
MD5:  60:0B:48:0D:DB:56:8C:68:8C:2D:94:4A:D6:DA:04:B8
SHA1: A7:CE:57:10:70:87:C1:2C:C0:9D:1D:90:8C:BB:69:B6:66:26:97:13
Signature algorithm name: SHA1withRSA
Version: 3


*******************************************
*******************************************
If everything went well, you might have successfully created server.jks and client.jks which can be used to secure Axis2 Services and access those secured services.

You can also find a summary of Java keytool commands at http://ruchirawageesha.blogspot.com/2010/07/java-keytool-keystore-commands.html

42 comments:

  1. Hi,

    This is a great, very informative tutorial. Thanks! I have one question though. How can the server/service know which of his clients is accessing the service?

    Thanks.

    ReplyDelete
  2. Thanks, very much
    Aleksandar Bosancic

    ReplyDelete
  3. This comment has been removed by the author.

    ReplyDelete
  4. Hi
    Thanks for your great post. It's very useful. I did my keystore problems.

    thanks
    juddi

    ReplyDelete
  5. Thanks a lot Wageesha for a very informative and to the point article on keystores.
    This helped me a lot !

    ReplyDelete
  6. This is a great post, but does anyone know about how you can validate a digital signature using the public cert? within a java program?

    ReplyDelete
  7. Thanks, you saved me a lot of time !

    ReplyDelete
  8. This is by far the most clear explanation that I've seen. Thanks!

    ReplyDelete
  9. That was nice for me.I used the server certificate for apache ftp server.
    Thanks..!!

    ReplyDelete
  10. the server that I need to contact supplied a pem file that contains a PrivateKey section above the Certificate section and keystore won't import that -- is there some other method for importing this key? I know the key works because I can use curl --cert key+cert.pem --cacert ca.pem and this contacts the remote site correctly, but I haven't been able to find an equivalent method through java. Any advice you can share on this would be most welcome.

    ReplyDelete
  11. Many thanks for the nice article...very well explained...

    ReplyDelete
  12. Thanks for the nice article.

    ReplyDelete
  13. Thanks for simple and clear explanation ...

    ReplyDelete
  14. Hi i was following steps which you described
    and got error javax.net.ssl.SSLException: hostname in certificate didn't match :

    ReplyDelete
  15. How do I create a new password in keystore? What exactly do I need to type in?

    ReplyDelete
  16. gr8... good info..

    ReplyDelete
    Replies
    1. This is a very good tutorial. Thank you very much.

      Delete
    2. in google chrome showing Certificate-based authentication failed showing error Error code: ERR_BAD_SSL_CLIENT_AUTH_CERT after your instructions i configure in tomcat


      and place their corresponding .jks in dir and also import client.cert in google chrome, can any one guess about this matter...

      Delete
  17. ThankYou..I just use this site whenever I need to configure the certificates.... :)

    ReplyDelete
  18. This blog has been really very helpful to me...thanks a lot...:)

    ReplyDelete
  19. Thanks a lot, it helped me very much

    ReplyDelete
  20. Wowww! Very neatly compiled and contains everything needed for SSL communication.. Great job Wageesha!!!

    ReplyDelete
  21. Many many thanks Dear...It's very neat and clean step by step approach to learn this thing..Really very great job...

    ReplyDelete
  22. Thanks Wageesha, your article saved a lot of my time :)
    Keep up the good work !

    ReplyDelete
  23. Concise and informative. Very helpful! Great job!

    ReplyDelete
  24. Thank you so much for taking the time to share this information. A great read. I’ll certainly be back.

    ReplyDelete
  25. Great post... worked smoothly. Thank you!

    ReplyDelete
  26. Great post..Thank you

    ReplyDelete
  27. Thanks. This was usefull. But has a question. In this case, is it not vulnerable that if someone gets hold of either of these .jks files, they can pretend to be client or server when they are actually not.

    ReplyDelete
    Replies
    1. If your client.jks has been stolen, the thief will be consider has the client. To protect you against this you should add a VPN on the top.

      Delete
  28. Thanks so much for the great tutorial

    ReplyDelete
  29. Same comment as Anonymous:
    --> This is by far the most clear explanation that I've seen. Thanks!

    ReplyDelete
  30. Great tutorial.Thank you so much.Can you please specficy how to convert the client trust store into .pem format .

    ReplyDelete