Docs‎ > ‎REST APIs‎ > ‎

Using SSL

When using your Espresso Logic API, you always have the option of using HTTP (insecure) or HTTPS (secure). If you choose HTTP, you should always remember that the data being passed back and forth between your client and the Espresso Logic server is in the clear. It can conceivably be intercepted and read by third parties.

If you use HTTPS, all communication between your client and the Espresso Logic server will be encrypted, making it impossible (or at least enormously more difficult) for a third party to intercept it and read it.

However, in order for HTTPS to work properly, there needs to be a way to ascertain that the Espresso Logic server is who it says it is. This is done using a certificate, which is issued by a Certificate Authority (CA). In the case of Espresso Logic, this Certificate Authority is GeoTrust.

GeoTrust is recognized as a Certificate Authority by all common web browsers. Therefore,  Javascript in the browser should be able to use the Espresso Logic HTTPS API with no difficulty.

Other client language environments may need to accept the GeoTrust certificate for SSL to work properly. Each language works differently.

Java and JVM languages (Scala, Groovy, Jython, etc...)

When writing a Java client that connects to the Espresso Logic service through HTTPS, you will typically encounter the following exception:

Exception in thread "main" javax.net.ssl.SSLPeerUnverifiedException: peer not authenticated
    at com.sun.net.ssl.internal.ssl.SSLSessionImpl.getPeerCertificates(SSLSessionImpl.java:352)
    at org.apache.http.conn.ssl.AbstractVerifier.verify(AbstractVerifier.java:126)
    at org.apache.http.conn.ssl.SSLSocketFactory.connectSocket(SSLSocketFactory.java:572)

This indicates that Espresso Logic's SSL certificate is not recognized as being signed by a valid authority. This in turn is caused by the Certificate Authority (in this case, GeoTrust) not being (by default) installed as a recognized CA in the Java JDK.

The quick and dirty way

If you just want to get going, follow these two steps:
  1. Download this keystore to your local drive and name it mykeystore
  2. Add the following line to your Java program, before you make any REST calls (make sure the path is correct):
System.setProperty("javax.net.ssl.trustStore", "/home/jdoe/MyProject/mykeystore");

And that should be it. If you'd like to understand this issue in more depth (recommended if you're going to use this seriously), read on for a lot more details.

The long and painful but, ultimately, correct way

There are two ways to overcome this problem: by installing the GeoTrust certificate in your own keystore, or by installing it in the JDK's main keystore. If you're not sure which to use, we recommend the first method.

Regardless, you'll need to obtain a copy of GeoTrust's certificate. Download it to your local drive and name it e.g. geotrust.cert
From now on, we will assume that this file is in /home/jdoe/MyProject/geotrust.cert

Locate keytool

You will also need to make sure that you can run the standard Java tool named keytool. Open a command line and try to execute it. If it is not found, you'll need to locate it. Normally, it is wherever the Java JDK is installed, under the bin directory.

Under Linux, this location will vary widely depending on your distribution. A sample location might be something like /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin

Under OSX, you can typically use $JAVA_HOME to refer to your JDK. A typical installation path would be /Library/Java/JavaVirtualMachines/1.6.0_29-b11-402.jdk/Contents/Home/bin

Under Windows, a common installation path for the JDK is something like c:\Program Files\Java\jdk1.7.0_25\bin

Once you have located the keytool command, you can continue.

Decide which keystore file to use

If you already have a CA keystore file, you'll most likely want to use that.
If you do not, then you can use either the JDK/JRE's global CA keystore, or your own.

The global CA certificate keystore is called typically in the lib/security directory of the JDK or JRE installation, and is usually called cacerts
If you use the global keystore, you will affect all Java programs running on your machine. This is typically fine, but in security-critical environments, that may be a problem. Also, you may not have write access to the global keystore file.

If you decide to use your own keystore file (recommended by default), then decide where it should be created, and what name to give it. Its name and location are entirely up to you.

In any case, from this point forward, we will assume that the keystore file is /home/jdoe/MyProject/mykeystore

Install the GeoTrust certificate

The next step is to import this certificate into the keystore file. If you do not use an existing keystore file, a new keystore file will be created for you.

To import the certificate into your keystore, you will need to run the following command:

keytool -import -alias GeoTrust -file /home/jdoe/MyProject/geotrust.cert -keystore /home/jdoe/MyProject/mykeystore

You may be prompted for a keystore password. If you are using an existing keystore, you'll need to enter its password (hint: the default password for keystores is often changeit ). If you do not already have a keystore, then the password will be used to create the new keystore file. The password can be empty, with the obvious security implications.

If all goes well, you should see output similar to:

Enter keystore password:
Owner: CN=*.espressologic.com, OU=Domain Control Validated - RapidSSL(R), OU=See www.rapidssl.com/resources/cps (c)13, OU=GT49596157, SERIALNUMBER=FQB5qKCvWu34p5U4gGfFdexoH0DBrYIt
Issuer: CN=RapidSSL CA, O="GeoTrust, Inc.", C=US
Serial number: bfef2
Valid from: Thu May 09 01:42:44 PDT 2013 until: Sun May 11 19:16:37 PDT 2014
etc...

with a lot more information, ending up with the question:

Trust this certificate? [no]:

Type yes and hit enter, and you should see:

Certificate was added to keystore

At this point, you have imported the certificate into the keystore.

If you used the JDK/JRE's CA keystore (cacerts), then you're done: you should be able to make HTTPS call to Espresso Logic's API.

If you used your own keystore, then you'll need to use it in your programs. The two most common ways of doing this are:

Using a JVM argument

When running your program, you can add a command-line parameter pointing to your keystore, e.g.:

java -Djavax.net.ssl.trustStore=/home/jdoe/MyProject/mykeystore com.acme.MyProgram

Adding a system parameter in code

You can do the same thing using code, by invoking the following before making any HTTPS calls (this is Java, other JVM languages will vary slightly):

System.setProperty("javax.net.ssl.trustStore", "/home/jdoe/MyProject/mykeystore");


You should now be able to make HTTPS calls to Espresso Logic's API.


ċ
geotrust.cert
(2k)
Max Tardiveau,
Jun 18, 2013, 4:38 PM
ċ
mykeystore
(1k)
Max Tardiveau,
Jun 18, 2013, 6:34 PM
Comments