Using SSL with Enhydra
Introduction
This document is a guide to developing Enhydra applications that use Secure
Sockets Layer (SSL). Although not a tutorial, if you use the development
checklist and the configuration file supplied, you can get the Golf Shop
Demo that comes with the Enhydra source code working under SSL.
System Requirements
-
JDK1.2. from Sun Microsystems or Blackdown JDK 1.2 (on Linux)
-
Your JDK must have keytool (located in JDK_HOME/jre/bin)
-
you will also need to download Sun's Java Secure Socket Extension Kit from
the Sun web site http://java.sun.com/products/jsse/
.
The Java Secure Socket Extension Kit contains implementations of cryptographic
algorithms, and is subject to US export restrictions: You cannot download
it outside of the US and Canada. Sun has made a weakened encryption version
available for export, see the JSSE
page.
Background
There are three ways to use SSL with Enhydra:
-
Associate Enhydra with a version of Apache
with SSL support through JServ.
-
Assoicate Enhydra with Netscape Enterprise server using WAI
-
Use SSL support directly built in to enhydra
The first two methods are documented elsewhere, I'll discuss the third
option here.
There are a variety of commercial SSL tool kits for Java on the market,
however as of September 1999, Sun has released the Java Secure Socket Extension
Kit (JSSE). This combines SSL features found in Sun's Java web server,
with the security API of JDK1.2. This is likely to be a defining standard,
for other commercial Java SSL vendors, though it may take some time for
the vendors to release their own implementations of JSSE.
JSSE is reasonably full featured, there have been 3 releases since
September with the final release in January 2000. Sun's implementation
is a reference release: they do not plan on supporting JSSE further. JSSE
implements SSL 3.0, and TLS, it is currently unclear how secure this implementation
is.
Installation and Configuration
Here are the basic steps to go through to get SSL working with Enhydra.
-
Install a version of Enhydra as usual with the built in SSL hooks.
-
If building from source configure the config.mk.
-
Download and install JSSE jar files
-
Edit your Java security policy file
-
Generate or install X509 Certificates
-
Modify enhydra configuration file to add the SSL connection method
These steps are explained in detail below.
-
Install Enhydra
Make sure that you have the version of Enhydra with SSL support. Enhydra
has no implementations of cryptographic algorithms, so its export outside
the US is not restricted.
-
Download and install JSSE jar files
JSSE is currently only available from Sun to download in the US and
Canada from http://java.sun.com/products/jsse
. Once you have downloaded the zip file, unzip and place the three jar
files in their locations.
As JSSE is a Java extension kit, if you place it in the JDKHOME/jre/lib/ext
directory, then the Java compiler and virtual machine will be able to find
the JSSE classes without changing the CLASSPATH.
If you do not have access to this directory you must run the Enhydra
configure script with the -jsse option. This flag takes as an
argument the directory containing the JSSE jar files.
-
Configure Make
If you are building Enhydra from source, then in your top-level config.mk,
set BUILD_JSSE=true.
-
Edit the Java security file
You can find your Java security file at JDK_HOME/jre/lib/security/java.security.
Find the list of security providers. The default is:
security.provider.1=sun.security.provider.Sun
To add the default JSSE security provider, add the following line:
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
The numbering refers to the order in which the security providers are
used. If you are using a vendor's implementation of JSSE, then the security
provider will be something else. See your vendor documentation.
-
Generate or install your X509 Certificates
if you are testing your setup you will want to generate your X509 certificate
yourself, but if you are building a production site, you will need to purchase
a certificate from a certificate authority such as Thawte or Verisign.
-
Generating your own certificate
Using the JDK keytool utility you can generate your own X509 certificates,
but be aware this is a memory intensive operation. In generating a certificate
you will need to give information to the keytool utility, do not lose
this information. At the command prompt (presuming that JDK_HOME/jre/bin
is in your path) enter:
$ keytool -genkey -alias name -keyalg RSA
You will then be prompted for the following information:
-
keystore password - if this is the first time that you are running this,
it will create a keystore in your home directory and you will be prompted
to create a keystore password. You will need this password every time you
use any key management. The alias is the name that will identify the key
in the keystore, you can have several keys in your keystore. If you do
not specify an alias the default name is mykey.
-
First and Last name e.g. "Bill Clinton"
-
Name of organizational unit, this is not a company name, but for maybe
for an internal department. e.g. "White House".
-
Name of your organization e.g "US Government"
-
City or location e.g "Washington"
-
State or Province eg "District of Columbia"
-
Country code e.g. "USA"
To verify that the key was properly created in the keystore you can verify
it with:
$ keytool -list
Important: The program will not work without the -keyalg
RSA option Netscape uses RSA encryption, but the keytool uses DSA
by default. At this point you will be prompted if the information is correct,
if it is then the program will proceed to generate a self signed certificate
and key. this may take some time.You will finally be prompted for a password
for the certificate. Make a note of this as you will not be able to use
the certificate without it.
-
Generating a certificate request
If you want a certificate from a recognized certificate authority,
then you will need to generate a certificate request. Once you have the
certificate request you can submit it to your certificate authority. See
your certificate authority for the proper procedure for doing this.
-
At the command prompt type:
$ keytool -certreq -file filename
The specified file will be where the certificate request will be written
to. If not specified the request will be output to standard out.
-
Importing a certificate
Once your certificate authority has issued your certificate, you can
import it into your keystore by issuing the command:
$ keytool -import -alias name -file certfile
Where certfile is the name of the issued certificate file.
Modifying Your Application
Now you can alter your Enhydra application configuration file so that it
can find the certificates and keys. For example, here is the configuration
file for the GolfShop demo shipped with the Enhydra source code. This configuration
file is in the directory:
GOLF_SHOP_HOME/output/
Add the following lines to the configuration file:
# begin ---------------------------------
Connection.golfPortSSL.Type = https
Connection.golfPortSSL.Port = 8443
Connection.golfPortSSL.SecureRandomAlgorithm =SHA1PRNG
Connection.golfPortSSL.SecureRandomProvider = SUN
Connection.golfPortSSL.SSLContextProvider = SunJSSE
Connection.golfPortSSL.SSLContextProtocol =TLS
Connection.golfPortSSL.KeyStoreLocation="/enhydra.enhydra.org/home/steve/.keystore"
Connection.golfPortSSL.KeyStoreProvider=JKS
Connection.golfPortSSL.KeyManagerAlgorithm = SUNX509
Connection.golfPortSSL.KeyManagerProvider = SunJSSE
Connection.golfPortSSL.TrustManager=JSSE
Connection.golfPortSSL.Password = your_password_here
Connection.golfPortSSL.ClientAuthentication=false
#
# Connect the port to the application
#
Channel.golfPortSSL.golfChannel.Servlet = GolfShopSSL
Channel.golfPortSSL.golfChannel.Url= /
Channel.golfPortSSL.golfChannel.Enabled = yes
#
# Specify applications (no admin).
#
Application.GolfShopSSL.ConfFile = GolfShopXMLC.conf
Application.GolfShopSSL.Description = "Enhydra Demo Secure Shopping
Cart Application (SSL)."
Application.GolfShopSSL.Running = yes
#end ------------------------------------------
This example uses the XMLC implementation of the GolfShop demo.
The remainder of this section explains each line in detail.
Connection.golfPortSSL.Type = https
Define the connection method, this is required if you want to use SSL.
Connection.golfPortSSL.Port = 8443
Define the port to connect to with the HTTPS method. The default port
for SSL is 443, but that is a privileged port on Unix and you will need
to be root to use it. The HTTP alternative ports are in the 8000 range.
If you are testing your application on a port other than 443, Internet
Explorer will not be able to connect to it. Netscape does not have a problem
with SSL on non-standard ports. A workaround is to use SSH port-forwarding
to bind port 44 on your local machine to the port on which Enhydra is running.
For example, if your Enhydra application is running on foo.bar.org
on port 8443 where I am user steve, then I invoke ssh: ssh -x -l steve
-L 443:foo.bar.org:8443 steve@foo.bar.org
Connection.golfPortSSL.SecureRandomAlgorithm =SHA1PRNG
Java security provides a cryptographically strong Pseudo Random Number
Generator (PRNG). This specifies the algorithm.
Connection.golfPortSSL.SecureRandomProvider = SUN
The provider refers to the providers in the java.security file, in our
case SUN or SSL
Connection.golfPortSSL.SSLContextProvider = JSSE
The SSLContext Provider currently defaults to JSSE. The SSLContext holds
the state of the SSL implementation. It is used to generate the factories
for the sockets.
Connection.golfPortSSL.SSLContextProtocol =TLS
This currently has two defaults SSL or TLS. TLS is a protocol that is
likely replacement for SSL 3.0.
Connection.golfPortSSL.KeyStoreLocation="/enhydra.enhydra.org/home/steve/.keystore"
The keystore is generated and managed by the keytool utility. The default
is to have it in your home directory.
Connection.golfPortSSL.KeyStoreProvider=JKS
The key store provider
Connection.golfPortSSL.KeyManagerAlgorithm = SUNX509
Currently SUNX509 is the only default value
Connection.golfPortSSL.KeyManagerProvider = JSSE
This is currently the only provider. The name may change to SunJSSE
in the future.
Connection.golfPortSSL.TrustManager=JSSE
The Trust manager
Connection.golfPortSSL.Password =
When you generated the key and certificate or the certificate request
you will have had to specify the password for it. At this point,
assuming that everything is correct you should be able tostart up enhydra
ands connect to it on port 8443.
Other sources of information
-
For general Java security see Java Security by Scott Oakes, published
by O'Reilly
-
An interesting book is Java2 Network security by Marco Pistoia published
by Prentice Hall. This has interesting and topical information, but the
sample code had many bugs.
-
The best source for JSSE are the javadoc files that come with the jar files.
In particular, there is an overview.html, API_users.html, and addtional.html
files which are very useful
-
The comp.lang.java.security mailing list has occasional things on JSSE
-
Sun has a mailing list archive at http://java.sun.com/security/hypermail/java-security-archive.
This has many intersting things related to JSSE.
steve.latif@lutris.com