Please consider my Linux addendum to the SSL configuration documentation. Or perhaps
someone could post this on a site somewhere:
SL HOWTO LINUX ADDENDUM
This document is Linux centric. You may be using a version of the JDK which contains
the hosed version of the keytool. If you are having trouble getting SSL to work in
Linux, and are being forced to go to a Windoze box to generate your keystore or are
getting any of the following error messages:
* keytool error: java.security.NoSuchAlgorithmException: RSA KeyPairGenerator not
available
* keytool error: java.lang.Exception: Failed to establish chain from reply
* keytool error: java.security.cert.CertificateException: IOException: Sequence tag
error
then this document may be helpful to you. Included in this document is the
www.orionserver.com SSL document and the www.orionsupport.com followup, just
in case you haven't seen it. If you have then by now they are frustratingly
familiar as are the replies to your cries of help that redirect you back to those
documents.
SETTING UP A SECURE SITE USING SSL
This guide explains how to set up a secure site that's accessible through the https
protocol. For setting up SSL in Orion, only
step 2 and 3 are necessary, but to use SSL you need a certificate and step 1 goes
through how to get a certificate from thawte for
testing purposes. For SSL you need JDK 1.3 or you have to download a third party
provider. Also, for some reason the
thawte-site might not work if you copy/paste using certain netscape versions.
1.Creating a keystore with a certificate:
keytool -genkey -keyalg "RSA" -keystore keystore -storepass 123456 -validity
360
keytool -certreq -keyalg "RSA" -file my.host.com.csr -keystore keystore
paste the .csr to https://www.thawte.com/cgi/server/test.exe
paste the result into my.host.com.cer
keytool -keystore keystore -keyalg "RSA" -import -trustcacerts -file
my.host.com.cer
You'll now have a "keystore" file in your current directory.
2.Creating a secure site:
Copy the default-web-site.xml config in the /config directory to
secure-web-site.xml and edit it.
Add secure="true" as an attribute to the <web-site ...> <web-site> tag.
Add <ssl-config keystore="../my/keystore" keystore-password="123456" /> the
keystore to the main body.
Install the site, this is done by adding %lt;web-site
path="./secure-web-site.xml" /> the site to server.xml.
3.Setting up cert-based client auth:
Add needs-client-auth="true" to the node.
Get a client cert for testing, this can be done at:
http://www.verisign.com/client/enrollment/index.html
Login as a user and register your profile, this can be done via the page
found at /demo/ssl/ssl-user-registration.jsp
CONFIGURIG SSL
First, realise that the documentation contained in
http://www.orionserver.com/docs/ssl-howto.html is correct, although
it leaves some important information out. Here are the first two parts of it,
replicated with my notes.
1.Creating a keystore with a certificate:
Note that the Linux keytool binaries that I tried (including Sun's and IBM's)
completely failed to use the RSA
algorithm, which is necessary. What I did was generate the keystore under
Windows, and then copy the
keystore file to Linux. However, this aspect is still untested; if anyone else
wants to independently verify that it
works, I'd appreciate it.
keytool -genkey -keyalg RSA -keystore keystore -storepass 123456 -validity
360
Note: the CN must match the fully qualified domain name of the machine. If
you're planning on using
"https://my.host.com/";, you'll need to use "my.host.com" as the CN.
keytool -certreq -keyalg RSA -file my.host.com.csr -keystore keystore
paste the .csr to https://www.thawte.com/cgi/server/test.exe
You will want to generate a key with a chained SSL key, not the default.
paste the result into my.host.com.cer
keytool -keystore keystore -keyalg RSA -import -trustcacerts -file
my.host.com.cer
You'll now have a keystore file in your current directory.
2.Creating a secure site:
Copy the default-web-site.xml config in the $ORION/config directory to
$ORION/config/secure-web-site.xml and edit it.
Add secure="true" as an attribute to the <web-site> node, and remove the
port attribute.
Add <ssl-config keystore="../my/keystore" keystore-password="123456" /> to
the
main body. The keystore path is relative from the $ORION/config directory.
Install the site, this is done by adding web-site
path="./secure-web-site.xml" /> to
$ORION/server.xml.
LINUX ADDENDUM
* Switch the JDK you are using
We use different JDK's for different things. Consequently, our servers have
multiple JDKs available: one via the CLASSPATH and several by manually
changing the CLASSPATH in the command for the servlet/application or whatever
we are doing. So, your task of setting up a new JDK may be much more
extensive and require serious strategizing if you are doing this on an
important production server. I did this on my workstation. I never use RPMs
for the JDK. Just grab that huge file over at java.sun.com and drop it into
JAVA_HOME/JDK_OF_YOUR_CHOICE and make a symlink to the one I want available
via the CLASSPATH.
The afore mentioned error messages I was getting didn't make much sense until
someone told that a couple of versions of the JDK had a malfunctioning
keytool. I didn't find any documenation on the Internet about that problem,
but that may be because I wasn't looking for it. Instead of going to a
different computer us the above keytool commands, I changed my JDK and the
commands worked like a champ! So try a different JDK.
* Now use the keytool
Now that you have changed which JDK you are using, reissue the above commands
and see if they don't work better for you. Instead of using a person's name I
wrote the name of the domain (www.whatever.com).
* www.thawte.com
The above information about www.thawte.com was a little inssuficient, so here
is how I generated my test cert:
type of certificate = Test SSL Chained CA Cert
certificate format = Netscape
* www.verisign.com
Verisign provides a free 14 day test certificate. They require a special
browser side certificate too so that they can curtail abuse of the free cert.
Just choose their server one and when you go to pay, select the free 14 day
trial. You won't have to provide any of the credit card information. At this
time I haven't pursued it, but I will soon.
* java.sun.com
As of the JDK 1.3 the SSL packages are optional. Apparently they will be
defaulted in as of the JDK 1.4 which is in beta currently. Anyway, it may be
neccessary for you to locate jsse.jar, jcert.jar and jnet.jar and place them
into JAVA_HOME/jre/lib/ext. Although I didn't benefit from this, it may be
neccesary depending upon which version of the JDK you choose to use. You can
grab the jars you need from the jsse part of sun.java.com.
BIOGRAPHY
Let me describe the system I solved the problem on:
* RedHat 7.0
* Kernel 2.2.14-5.0
* I didn't install RedHat's version of java
* I didn't RPM java, I used the source (there is no building process, just put
it into your CLASSPATH.
* I was using IBM's 1.3 and switched to Sun's 1.3
If you find this document useful, please send one bottle of your favorite beer
to:
Jerry Cornelius
c/o Web-X, Inc.
738 Broadway
Ste. 100
Tacoma, WA 98402
