Use Secure Sockets Layer for HTTP Calls

You can set up to make HTTPS calls to Live API Creator's API using Secure Sockets Layer (SSL). You can use HTTP (insecure) or HTTPS (secure). If you choose HTTP, the data passed back and forth between your client and the API 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 API Server is 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 API 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 API Creator 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 API Creator 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 Live API Creator 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 API Creator'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, complete the following 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. The path must be correct:
System.setProperty("javax.net.ssl.trustStore", "/home/jdoe/MyProject/mykeystore");

The long and painful but, ultimately, correct way

Prerequisite: Obtain a copy of GeoTrust's certificate. Download it to your local drive and name it e.g. geotrust.cert. In the following procedures, this file is assumed to be located in the /home/jdoe/MyProject/geotrust.cert directory.

You can install the GeoTrust certificate in the following keystores:

  • (Recommended) In your own keystore.
  • In the JDK's main keystore.

Locate the Keytool

Ensure that you can run the standard Java tool named keytool. Open a command line and try to execute it. If it is not found, locate it. Typically, it is where the Java JDK is installed, under the bin directory.
  • Under Linux
This location can vary 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

Decide which Keystore File to Use

Prerequisite: You have located the keytool command. (Recommended) Use the JDK/JRE's global CA keystore file 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 the location you want to save it to and the name to give it. In the following examples, the keystore file is /home/jdoe/MyProject/mykeystore.

Install the GeoTrust Certificate

Import this certificate into the keystore file. If you do not use an existing keystore file, a new keystore file is created for you.
  1. Run the following command:
    keytool -import -alias GeoTrust -file /home/jdoe/MyProject/geotrust.cert -keystore /home/jdoe/MyProject/mykeystore
  2. If prompted, enter the keystore password. If you are using an existing keystore, enter its password (hint: the default password for keystores is often changeit ). If you do not already have a keystore, then the password is used to create the new keystore file. The password can be empty, with the obvious security implications.
    The following output is expected:
    Enter keystore password:
    Owner: CN=*.ca.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...

    Trust this certificate? [no]:
  3. Type yes and hit enter.
    The following output is expected:
    Certificate was added to keystore

You have imported the certificate into the keystore. If you used the JDK/JRE's CA keystore (cacerts), then you are done. You should be able to make HTTPS call to API Creator's API.

If you used your own keystore, then use it in your programs. The two most common ways of doing this are:
  • Use a JVM argument
  • Add a system parameter in code

Use 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

Add 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 can make HTTPS calls to Live API Creator's API.