This document explains how to secure HTTPS traffic with SSL/TLS using iSaSiLk.
We give a quick rundown of the demo and explain how the API can be used.
Basically what the code allows you to do is to use HTTPS URLs with the
java.net.URL class, open connections to
perform requests and read responses, just like standard HTTP URLs
are supported in the JDK.
This document does not give a complete description
of all features of Java™ URLs and HttpURLConnections,
please refer to the iSaSiLk and JDK JavaDoc files or additional information.
HTTPS is nothing more than the HTTP protocol over SSL/TLS rather
than over plain TCP. As such it would be quite easy to add HTTPS to any
HTTP implementation given the necessary hooks for the transport are
provided or the source is available.
Unfortunately this is not the case for the HTTP code that comes with the JDK.
As developing a stable and fairly complete implementation of HTTP/1.1 would
be a serious undertaking and reinventing the wheel is something we prefer to
avoid, we decided not to do yet another HTTP implementation and to use the
W3C's HTTP code that comes with their Jigsaw Web server instead (see license
Essentially what we did was to take the Jigsaw source (current version 2.2.6), remove a
lot of classes which are not required for HTTP URL support, and modify
a few classes to allow for HTTPS. We provide the result as the JAR
file w3c_http.jar which has to be used in addition to
the iSaSiLk iaik_ssl.jar file for HTTPS support.
As a sidenote we would also like to point at that there is at least one third
party HTTP implementation that can be used with iSaSiLk to provide
HTTPS support. It is called HTTPClient , is free under a LGPL license and
available online .
Please note that this is a pointer to a possible alternate solution
only and not an endorsement of this software. As a matter of fact we have
never evaluated it and of course cannot answer any support questions about it.
This section explains how to actually use HTTPS by describing the demo
supplied with the iSaSiLk distribution. Its source is located in
HttpsDemo.java example and it is available in
compiled form in the iaik_ssl_demo.jar file.
To try out the demo do the following (assuming you are using the IAIK JCE
as your cryptographic provider and a JDK version on a Windows platform):
Note that the HTTPS code requires
in addition to
The demo then will open a HTTPS connection to https://jce.iaik.tugraz.at/ , display
some status information and then print the downloaded HTML page. You can select
a different server by passing its URL as argument to the demo.
As shown in the demo using HTTPS is very simple. Summarized, the steps to
The HTTPS protocol has to be registered with the
APIs before it can be used. There are several options:
For cases where the above approaches cannot be used we provide a limited
workaround. Because HTTPS URLs cannot even be created if no appropriate
protocol handler is installed they cannot be used in this case but it is
still possible to speak HTTPS via the provided implementation. To do this
create a HTTP (!) URL specifying the target host and port and pass it
directly to the constructor of the class iaik.protocol.https.HttpsURLConnection .
For example, use code like this:
Note that you
specify a destination port in this case,
you cannot use the default port (80 would be used as for HTTP). Also note that
this is a limited workaround only, we recommend using it only if the other options
are not available. This problem is due to a limitation in the JDK software
and not in ours.
HTTP defines a number of request methods. Most often used is the GET
method, which is appropriate to retrieve data from the server.
Another request method is POST, which is most usefull to send large
amounts of data to the server. iSaSiLk supports both.
However, in difference to the original JDK HTTP implementation the POST
method is not automatically chosen if you enable both input and output
for the connection. To use the POST method use code like this:
Please note the order in which the methods are executed and also that
all data must be written before calling getInputStream() .
For connecting via a proxy the host name and port number of the proxy have to
be set as System properties using "https.proxyHost" and
"https.proxyPort" as key words, e.g.:
If the proxy requires a user to authenticate him/herself by username and
password, this either may be done in the common way by setting a request
property on the HttpsURLConnection object or by specifying user name and
password via System properties.
When setting proxy user name and password via request property you have to
use "Https-Proxy-Authorization" as key. The value consists of
authentication scheme ("Basic") and username/password encoding (base64) as
accustomed from normal (proxy) authentication, e.g.:
Please ensure to use "Https-Proxy-Authorization" as key only when
connecting through a authentication requesting HTTPS proxy! Do not use another
key like "Proxy-Authorization" or
"Authorization". It would not be recognized and so may travel
to the target server. You may test the behaviour of your proxy by connecting
through it to an iSaSiLk server to see what is actually send to the server.
When setting HTTPS proxy user and password via System properties (may not be
the recommended way except you are sure that no one else may have access to your
client machine), use "https.proxyUser" and
"https.proxyPassword" as keys:
Moreover, it is possible to specify a list of hosts for which the library should
not use a proxy. This can be done using the https.nonProxyHosts
property. The use is similar to the http.nonProxyHosts property.
The value of this property is a '|' separated list of host names. The '*' as wildcard character
is allowed as first character of a name in the list. For example:
For a host that matches any of the names in this list, the library will establish
the connection directly without using the proxy.