Simple OpenSSL / Aolserver Installation Guide

By Pascal Scheffers (pascal@scheffers.net)

Introduction

I don't like network sniffing. I hate password stealing. I hate a h4x0r3d box. That's why I use SSH instead of telnet. That's why you should too. And while you're at it install OpenSSL for AOLServer too.

I hope this document will guide you to a working SSL server. Although it focusses on openssl, everything here should work for nsssl as well. I encourage everyone to use OpenSSL instead of nsssl(e), as SSLv3/TLSv1 are much, much better protocols than SSLv2. Also, with OpenSSL you will be able to use client certificate logon and CRL checking. 

This procedure describes howto do compile and install openssl and nsopenssl on a RedHat 6.2. It should be very similar on any other unix.
 
Prerequisites

OpenSSL 0.9.6 
You can get this from: http://www.openssl.org/source/openssl-0.9.6.tar.gz
nsopenssl 1.0
Get this from aolserver.com, the modules section.
ftp://ftp.aolserver.com/pub/modules/aolserver3_x/nsopenssl_1_0.tar.gz
Compiling

OpenSSL

As always, extracting tar files should be done as a normal user, not root. It does not matter where you compile openssl so you can use /tmp.

 $ cd /tmp
 $ tar xzf openssl-0.9.6.tar.gz 

Now you need to configure and make, you can run ./config with no parameters which will install openssl in /usr/local/ssl. I prefer /usr/local/openssl to prevent confusion. 
 
 $ cd /tmp/openssl-0.9.6
 $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
 $ make

Now it is of VITAL that you run the tests, cryptography will not work if the compiler makes a mistake. The incorrect result will run just fine, except nobody will be able to make connections or worse... 

 $ make test

And finaly install the libs and headers.

 $ su
 $ make install
 $ exit

Compiling nsopenssl

Just to warn you:

/*
 * nsopenssl.c
 *
 * This module implements an SSL socket driver using the OpenSSL library.
 *
 * WARNING THIS IS ALPHA SOFTWARE. IT HAS NOT BEEN TESTED AND SHOULD NOT
 * BE USED IN A PRODUCTION ENVIRONMENT. USE AT YOUR OWN RISK.
 *
 */

That means everyone should build and test it ;-)

nsopenssl requires that you use nsd8x. Solaris users must check the readme.txt file. Extract the tar file in a directory that also holds the aolserver source directory. In my case that is /web/root/, which is what I got after extracting Aolserver+ad12 to /web/.

 $ cd /web/root
 $ tar xzf /tmp/nsopenssl_1_0.tar.gz

and then make

 $ make OPENSSL=/usr/local/openssl/

and install:

 $ make install INST=/usr/local/aolserver

(or 'cp nsopenssl.so /home/aolserver/bin/', if that is where your aolserver lives)

Configuring Aolserver

You need to add the following section to your nsd.tcl file:

ns_section "ns/server/${servername}/module/nsopenssl"
ns_param port                     $httpsport
ns_param hostname                 $hostname
ns_param CertFile                 ${homedir}/servers/${server}/modules/nsopenssl/cert.pem
ns_param KeyFile                  ${homedir}/servers/${server}/modules/nsopenssl/key.pem
ns_param Protocol                 All
#ns_param Protocol                 SSLv2
#ns_param Protocol                 SSLv3
#ns_param Protocol                 TLSv1
#ns_param CipherSuite              "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"
ns_param ClientVerify             false
ns_param CADir                    ca
ns_param CAFile                   ca.pem 
ns_param Trace                    false

To load the module, search for this section in your nsd.tcl:

#
## nsssl: loads only if requisite files already exist (see top of this
# file). 
#
if { [file exists $sslcertfile] && [file exists $sslkeyfile] } { 
    ns_param nsssl ${bindir}/nsssle.so 
} else { 
    ns_log warning "nsd.tcl: nsssl not loaded because key/cert files do not exist."
}

and change all the 'nsssl' and 'nsssle' to 'nsopenssl':

#
## nsopenssl: loads only if requisite files already exist (see top of this
# file). 
#
if { [file exists $sslcertfile] && [file exists $sslkeyfile] } { 
    ns_param nsopenssl ${bindir}/nsopenssl.so 
} else { 
    ns_log warning "nsd.tcl: nsopenssl not loaded because key/cert files do not exist."
}

Creating a certificate

nsopenssl does not load if it does not have a server certificate to present to the https-client. Server certificates are mandatory in the SSL specification, so you'll need to get and install one. But first test the setup with the test key and certificate provided with nsopenssl. You cannot use this in a production environment, becaas Internet Explorer and Netscape will keep complaining that the hostname in the certificate does not mat

First create the directory that will keep the key and certificate file:

 $ cd /home/aolserver/servers/acs3-pg/modules
 $ mkdir nsopenssl
 $ chmod 700 nsopenssl
 $ cd nsopenssl

Create a key file:

 $ openssl genrsa -out key.pem 1024

And create a certificate request with that key, you will need to answer some questions the most important one is 'Common Name', this MUST be your hostname! Only Common Name is required, for the SSL-RFC, but your Certificate Authority (Verisign, Thawte, etc) will require some other of the other fields. Just fill them all out, to be safe. The last two questions may be required for the registration procedure of some certificate authorities.

 $ openssl req -new -key key.pem -out request.pem

Country Name (2 letter code) [AU]:NL
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:Zeist
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Pascal's OpenACS Project
Organizational Unit Name (eg, section) []:.
Common Name (eg, YOUR name) []:pascal.scheffers.net
Email Address []:pascal@scheffers.net

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

You can now send the request.pem file to some commercial Certificate Authority (or you can begin your own, to which I'll come back later). And wait for the certificate.

But let's not wait and create a test certificate in the mean time:

 $ openssl req -x509 -days 30 -key key.pem -in req.pem -out cert.pem

Now you have a certificate, you can restart your Aolserver. 

 $ su -
 $ restart-aolserver acs3-pg

and, with your favourite https capable browser goto https://yourserver.com/.

When you get your certificate from the CA

You may have to convert it from binary/DER to PEM format:

 $ openssl x509 -inform der -in certificate.crt -out cert.pem


Obtaining a server certificate with Internet Explorer.

Most Certificate Authorities have an website that lets you request a certificate with Internet Explorer. It is very simple to convert such a certificate to a cert.pem and key.pem file. After you have obtained the certificate (do make sure that you keep the key exportable when you request the certificate!), you must first export it to a file:

From internet explorer, open the Tools menu, and choose Internet options. 
On the 'Content' tab click the 'Certificates' button. Select your server certificate and click 'export'.

Select that you want to export the private key, on the .PFX options, DO NOT include all certificate in the path and DO NOT enable strong protection. When asked to, provide a nice and long password if you need to transfer the resulting certificate.pfx file over email. 

Now on your server machine:
 $ cd /home/aolserver/servers/acs3-pg/modules/nsopenssl
 $ openssl pkcs12 -nodes -in certificate.pfx -out cert.pem 

The resulting cert.pem will contain both the certificate AND the key. You can either remove the key from this file and put it in a key.pem file or do as I do: change the keyfile parameter in acs3-pg.tcl from .../key.pem to .../cert.pem.

That's it. You now have a https capable OpenACS installation. 

Credits

This document was written by Pascal Scheffers (pascal@scheffers.net) for the OpenACS project. 
I relied on the documentation efforts of the people from the OpenSSL project and the nsopenssl readme.txt. Thank you.