Project Open 3.5.x

Project Open, Linux, and SSL — Easy as Pie!

Installing SSL for Project Open on Linux is easy as pie!

If you like cement pie.

Actually, like many things open source, once you find the secret keys, it’s not hard at all. It’s finding those keys that inhales your time. I’m happy to share what I’ve found in the hopes that a) it’ll save you time and b) karma is real.

For this to work, you’ll need to have the following already in place:

  1. Operating System: You should be running a modern Linux distribution. I use CentOS, and I highly recommend it. These procedures should work without modification on CentOS 5.x and RedHat 5.x. Other Distributions or versions might force some procedural modifications.
  2. Perl: You should have Perl installed. It’s used (along with OpenSSL) to generate SSL keys.
  3. OpenSSL: Speaking of SSL keys, you’ll need to have OpenSSL installed. It’ll do most of the work to actually build the SSL key you’ll use.
  4. Project Open: Obviously, you’ll already need to have Project Open up and running. I’ve tested these procedures with versions 3.4.x and 3.5.x.
  5. AOLServer source code: You’ll need the file aolserver-4.5.0-src-tar.gz. It contains the source code for AOL Server, which is the web server on which Project Open is based. We’ll need this to compile the SSL support, because the default Project Open installer’s version of AOL Server doesn’t have SSL enabled.
  6. NSOpenSSL: The file nsopenssl-3.0beta26-src.tar.gz contains the source code for SSL support that AOL Server can use. I had to find at least beta 26; versions I tried before beta 26 didn’t work.
  7. root access: You’ll need to know the root password on your Project Open server. At the very least, you’ll need fairly open sudo permissions.
  8. C compiler: You’ll need C and its libraries installed in order to compile the SSL support code.

If you have all of those things, you’re ready to start!

First, transfer the files to your Project Open server. However you need to do it, get the files into this directory:


/root/deploy

Become root:


su -l

Create a directory into which to install the source code:


cd /usr/local/src
mkdir aolserver
cd aolserver

Un-tar the two tars into the target directory:


tar -zxvf /root/deploy/aolserver-4.5.0-src-tar-gz
tar -zxvf /root/deploy/nsopenssl-3.0beta26-src.tar.gz

Now that you have the source code where it’s available to work with, it’s time to start compiling:


cd nsopenssl-3.0beta26
make OPENSSL=/usr/include/openssl

The output should look something like this:


ar: creating libnsopenssl.a
a - sslcontext.o
a - ssl.o
a - tclcmds.o
a - x509.o
ranlib libnsopenssl.a

Now it’s time to actually install the code you just compiled:


make install OPENSSL=/usr/include/openssl AOLSERVER=/usr/local/aolserver

You should see several lines of output, and the last line should look like this:


ranlib /usr/local/aolserver//lib/libnsopenssl.a

It’s always a good idea to confirm that things went as well as they seem. You can confirm that the two key shared objects were created with these two commands:


ls /usr/local/aolserver/bin/nsopenssl.so
ls /usr/local/aolserver/lib/libnsopenssl.so

If both files are there, the compile and install steps worked. That means AOL Server should now be in a position to support SSL, provided we do two more things:

  1. Generate an SSL certificate for it to use.
  2. Configure AOL Server to use the new certificate.

It’s best to create the certificates in the context of the projop (Project Open) user ID. We’ll also store the certificates within the /web/projop directory structure so any backup jobs you might have will capture them. Start by becoming the projop user:


su -l projop

Create the necessary directory structure:


cd /web/projop/etc
mkdir certs
cd certs

Create the self-signed certificate:


perl /etc/pki/tls/misc/CA -newcert

This command will prompt you for several bits of information:

  1. Enter PEM pass phrase: This is your password. Make sure it’s complex. And don’t lose it.
  2. Verifying – Enter PEM pass phrase: Re-enter the same thing you entered for the PEM pass phrase.
  3. Country Name (2 letter code) [GB]: I entered “US” for my country code. Enter yours as appropriate.
  4. State or Province Name (full Name) [Nerkshire]: If you’re in the US, enter something like MI or OH.
  5. Locality Name (eg, City) [Newsbury] Enter your city, like Pittsburg or Columbus.
  6. Organization Name (eg, company) [My Company Ltd]: I entered Interstell Software.
  7. Common Name (eg, your name or your server’s hostname) [ ]: I entered ohcmhsrv020.interstell.home.
  8. Email Address [ ]: I entered tcrow@interstell.home.

After you enter all of that, you should see a response that looks like this:


Certificate is in newcert.pem, private key is in newkey.pem

Now prepare the certificate for use:


openssl rsa -in newkey.pem -out keyfile.pem

You should see this response:


writing RSA key

You can confirm the three files are present with this command:


ll

You should see three files:

  1. keyfile.pem
  2. newcert.pem
  3. newkey.pem

If all three are present, there’s just one thing left: configure AOL Server to use the certificate.

This piece too me longer to figure out than all of the others combined (and finding the right nsopenssl module took me longer than I care to admit!). We’ll start by making a backup of the configuration file so that if things go wrong, we can recover:


cd /web/projop/etc
cp config.tcl config.tcl.pressl

Now, use your favorite text editor (like vi or gedit) to open config.tcl. Look for this section:


#---------------------------------------------------------------------
#
# OpenSSL
#
#---------------------------------------------------------------------

Leave that heading intact. Delete everything down to, but not including, this section:


#---------------------------------------------------------------------
#
# Database drivers
# The database driver is specified here.
# Make sure you have the driver compiled and put it in {aolserverdir}/bin
#
#---------------------------------------------------------------------

In other words, delete the whole SSL section except its heading. Now, paste this into its place:


# SSL contexts. Each SSL context is a template that SSL connections are created
# from. A single SSL context may be used by multiple drivers, sockservers and
# sockclients.

ns_section ns/server/${server}/module/nsopenssl/sslcontexts
ns_param users “SSL context used for regular user access”


# We explicitly tell the server which SSL contexts to use as defaults when an
# SSL context is not specified for a particular client or server SSL
# connection. Driver connections do not use defaults; they must be explicitly
# specificied in the driver section. The Tcl API will use the defaults as there
# is currently no provision to specify which SSL context to use for a
# particular connection via an ns_openssl Tcl command.


ns_section ns/server/${server}/module/nsopenssl/defaults
ns_param server users


ns_section ns/server/${server}/module/nsopenssl/sslcontext/users
ns_param Role server
ns_param ModuleDir ${serverroot}/etc/certs/
ns_param CertFile newcert.pem
ns_param KeyFile keyfile.pem
ns_param CADir ca
ns_param CAFile ca.pem
ns_param Protocols "SSLv2, SSLv3, TLSv1"
ns_param CipherSuite "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"
ns_param PeerVerify false
ns_param PeerVerifyDepth 3
ns_param Trace false


# SSL drivers. Each driver defines a port to listen on and an explitictly named
# SSL context to associate with it. Note that you can now have multiple driver
# connections within a single virtual server, which can be tied to different
# SSL contexts. Isn't that cool?


ns_section ns/server/${server}/module/nsopenssl/ssldrivers
ns_param users "Driver for regular user access"


ns_section ns/server/${server}/module/nsopenssl/ssldriver/users
ns_param sslcontext users
ns_param port $httpsport
ns_param hostname $hostname
ns_param address $address


# OpenSSL library support:
#ns_param RandomFile /some/file
ns_param SeedBytes 1024

Note that this installation should enforce more complex encryption to keep your data in transit more safe.

Near the top of the file, you should see a line that looks like this:


set address "192.168.1.20"

Double check that your address is there. If it’s not, change the address that’s there to match your server.

Save your changes.

At this point, if all went well, you should be able to restart your server with this command (issued as the root ID):


killall nsd -9

Give the server a few moments to restart, then try to hit this URL (of course, substitute your hostname or IP address):


https://ohcmhsrv020.interstell.home:8443

It should come up with a warning that the certificate authority isn’t trusted. That’s okay. You’re using a self-signed certificate, and browsers will warn you about it. You could go to the expense of buying a commercial certificate, but I’ve never felt the need for an internal server.

At this point, you should have a Project Open server that’s protected by SSL.

I hope this has been helpful!

terrance
Terrance A. Crow is the Manager of Global Security at a global library services company. He holds a CISSP and has been writing applications since the days of dBASE III and Lotus 1-2-3 2.01.
https://www.interstell.com