Yet another InstallCert for Java, now with STARTTLS support

⇓ ... now forked at GitHub

added on 2017-10-21

---

Many of the Java folks, who ever dealt with SSL-enabled protocols and self-made SSL certificates, know of the InstallCert tool. This simple command-line tool, published in 2006 by Andreas Sterbenz at the official Sun blog, allows obtaining SSL certificates as they are presented by the hosts we connect to, with further optional saving them to the system trust store.

Sun's blog is not with us any more, but a copy of the original InstallCert publication and code is still available from some of the users' blogs, like this one, or archives like that one. Curiously, one of the current blogs at Oracle mentions this tool, but without reference to the original author, and with a reference (currently somewhat outdated) to the mentioned user blog instead... ☺

Well, the original Andreas' tool served faithfully to me for quite a while, but every good thing has its limitations... In particular, the original InstallCert could not deal with hosts that operate using STARTTLS technique.

The new code

Diving into STARTTLS required quite a refactoring of the original code, though the main parts of it are still in place ☺. In particular, modular approach was taken to deal with STARTTLS implementations for different protocols, so the code does not fit in single Java file any more, but is rather packaged as an executable .jar.

It is now possible to obtain certificates from hosts that not only speak plain SSL/TLS, but also expose their certificates via STARTTLS over IMAP, POP3, SMTP and LDAP.

For new application-level protocols with STARTTLS extension to be supported, an abstract STARTTLS handler is defined as a StarttlsHandler interface. This interface needs to be implemented by every new protocol handler, and the latter is to be registered with the Starttls wrapper class. This registration needs to be hard-coded so far. But keeping in mind the small number of STARTTLS-compatible application-level protocols yet to be implemented, this should not be a problem ☺.

The certificates collected by the program are now stored at two locations:

• the standard jssecacerts keystore in the lib/security folder of your JRE;
• in an extracerts keystore in your current directory; the latter may be handy in order to save collected certificates in pure form for further redistribution.

One of the new features is also the new template for collected certificates' aliases. They are now named like "host - certificate_subject" for better human readability ☺.

Downloads

The following downloads are available:

• binary:
  • http://www.usn.pp.ru/downloads/java/jsse-util-installcert/20140115/export/installcert-usn-20140115.zip
  • https://drive.google.com/uc?export=download&id=0B2nLiheurgV7Z1hxc3hMMGo0NWc
• source:
  • http://www.usn.pp.ru/downloads/java/jsse-util-installcert/20140115/export/installcert-usn-20140115-full.zip
  • https://drive.google.com/uc?export=download&id=0B2nLiheurgV7WU9lOU9tdXpPR2c

Please feel free to use and modify. The original license looks like 3-clause BSD one.

Usage – HOW-TO

Prerequisites

1. Download the binary distribution archive from here or here.
2. Unzip it to a location of your choice.

Obtaining a certificate from a plain SSL/TLS or an LDAP/STARTTLS server

Run the program like this:

java -jar installcert-usn-20140115.jar host_name

or

java -jar installcert-usn-20140115.jar host_name:port

or

java -jar installcert-usn-20140115.jar host_name:port truststore_password

The default port is 443 (for HTTPS). The default truststore password is "changeit" as per JSSE convention.

Obtaining a certificate from an IMAP / POP3 / SMTP server with STARTTLS extension

In this case you will need the JavaMail library, and make sure you have it on your classpath. Please also keep in mind that it is necessary to indicate the main class explicitly in the command line if you have more than one jar.

To make things easier, two shell scripts are provided: run-with-javamail-starttls.sh for Unix and run-with-javamail-starttls.cmd for Windows. You will have to edit at least one of them first, so to reflect the actual location of the JavaMail .jar file.

General notes and final housekeeping

If the program succeeds in obtaining a certificate (or several of them), and the certificates are not known yet, it will ask you whether you wish to save them. Upon successful run the program saves the new certificate(s) to two files, as mentioned above:

• the standard jssecacerts keystore in the lib/security folder of your JRE;
• an extracerts keystore in your current directory; this one may be handy in order to save collected certificates in pure form for further redistribution.

The first one will be needed by your software for normal JSSE operation. The second one is a good candidate for "clean" storage of your selected certificates.

Please keep in mind that in order to have the standard jssecacerts keystore file in the lib/security folder of your JRE successfully created/modified, you will most likely need to have administrative (superuser, root) privileges.

Enjoy! ☺

---

... rebuilt for Java 1.6 and fixed

added on 2014-01-15

The download links and examples were updated to reflect the new build made to be compatible with Java 1.6 as per Eric's comment. The certificate handling logic was also improved for better discrimination of new certificates vs known ones.

---

... now forked at GitHub

added on 2017-10-21

This code is now forked and available at Github: https://github.com/spyhunter99/installcert . The fork was created with an intention to achieve embeddability, and looks actively developed...