Use Secure Sockets Layer for HTTP Calls

You can make calls to Live API Creator's API using HTTP (insecure) or HTTPS (secure). With HTTP, the data passed back and forth between your client and API Server is in the clear. Third parties can conceivably intercept and read the data you are passing. With HTTPS, all communication between your client and API Server is encrypted, making it impossible (or at least enormously more difficult) for a third party to intercept it and read it.

This article explains how to set up to make HTTP calls to Live API Creator's API using Secure Sockets Layer (SSL).

GeoTrust as the Certificate Authority

HTTPS requires a way to ascertain that API Server is who it says it is. This is done using a certificate, which is issued by a certificate authority (CA). API Creator uses the GeoTrust certificate.

All common web browsers recognize GeoTrust as a certificate authority. You can use the API Creator HTTPS API using JavaScript in your web browser. Other client language environments may need to accept the GeoTrust certificate for SSL to work properly. Each language works differently.

For more information:

Writing Java Clients that Connect to Live API Creator through HTTPS

When writing a Java client that connects to Live API Creator through HTTPS, you may 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 exception 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.

By default, the GeoTrust CA is not installed as a recognized CA in the Java JDK. To prevent this exception, you must install the GeoTrust CA.

Install the GeoTrust Certificate Authority (the Quick-and-Dirty Way)

If you just want to get going, complete the following steps:

  1. Download the mykeystore file to your local drive and name it mykeystore.
  2. Add the following line to your Java program, using a correct path:
    System.setProperty("javax.net.ssl.trustStore", "/home/jdoe/MyProject/mykeystore");
The GeoTrust certificate authority is installed. You can now make your REST calls.

Install the GeoTrust Certificate Authority (Recommended)

Prerequisite: You have obtained a copy of GeoTrust's certificate, downloaded it to your local drive, and named it (for example, geotrust.cert). In the following procedures, this file is assumed to be located in the /home/jdoe/MyProject/geotrust.cert directory.

Locate the Keytool Command

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.
  • (In 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
  • (In 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
  • (In Windows)
A common installation path for the JDK is something like c:\Program Files\Java\jdk1.7.0_25\bin

Import the GeoTrust Certificate into a Keystore

Prerequisite:

  • You have located the keytool command.
  • You have decided which of the following keystore files to import the GeoTrust certifcate:
    • The JDK/JRE's global CA keystore file. The global CA certificate keystore file typically is located in the lib/security/cacerts directory of the JDK or JRE installation. Verify that you have write access to this keystore.
      Note: Using the global keystore file affects all Java programs running on your machine. This is typically fine, but in security-critical environments, this can cause issues.
    • (Recommended) Your own keystore file. If you decide to use your own keystore file, 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.
  1. Issue the following command:
    keytool -import -alias <alias name> -file <certificate file location> -keystore <keystore file location>
    For example:
    keytool -import -alias GeoTrust -file /home/jdoe/MyProject/geotrust.cert -keystore /home/jdoe/MyProject/mykeystore
    The GeoTrust certificate is imported into an alias and into the keystore. If you do not use an existing keystore file, a new keystore file is created for you.
  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 press the Enter key.
    The following output is expected:
    Certificate was added to keystore

You have imported the GeoTrust certificate into the keystore. If you used the JDK/JRE's global CA keystore file, then you are done. You should be able to make HTTPS call to Live API Creator's API. If you used your own keystore, then use it in your programs.

Run your Programs Using your own Keystore

You can run your program using your own keystore using one of the following methods:
  • Use a JVM argument

Add a command-line parameter pointing to your keystore, for example:

java -Djavax.net.ssl.trustStore=/home/jdoe/MyProject/mykeystore com.acme.MyProgram
  • Add a system parameter in code

Invoke the following before making any HTTPS calls, for example:

Note: The following example is Java. Other JVM languages vary slightly.

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

You can make HTTPS calls to Live API Creator's API.