AOLserver SSL Configuration Guide

$Header: /cvsroot/aolserver/aolserver.com/docs/admin/nsssl.html,v 1.2 2002/09/26 19:51:32 kriston Exp $

WARNING--READ BEFORE USING NSSSL

EXPORT NOTICE

This source code is subject to the U.S. Export Administration Regulations and other U.S. law, and may not be exported or re-exported to certain countries (currently Afghanistan (Taliban-controlled areas), Cuba, Iran, Iraq, Libya, North Korea, Serbia (except Kosovo), Sudan and Syria) or to persons or entities prohibited from receiving U.S. exports (including Denied Parties, Specially Designated Nationals, and entities on the Bureau of Export Administration Entity List).

Introduction

While fully functional for providing security over the internet using the "HTTPS" protocol. This implementation of nsssl supports SSL v2 which by itself is more than adequate for most web sites. Some seldom-used SSL v2 features that were omitted include client certificates and the SHA-1 message digest algorithm. The reasoning behind this is that users browsing the web very seldom have client certificates, let alone know what they are intended for. Likewise, in virtually all cases, MD5 is the message digest requested by all browsers and is fully supported. In any event, we always welcome contributions to add these features to nsssl.

Key Pair and Certificate Request Generation

SSL key pair and certificate request generation is handled by a Tcl script that you source into a stand-alone AOLserver process. To use, change to your AOLserver's root directory and edit the certificate information at the top of the "./modules/nsssl/keygen.tcl" file.

Once you are satisfied with your information, create your key pair and certificate request by typing:

./bin/nsd -ft ./modules/nsssl/keygen.tcl

Your directory will now include two files, "keyfile.pem" and "certreq.pem." Put the "keyfile.pem" file in a safe place for now. Send the "certreq.pem" file to your favorite Certificate Authority.

What To Do Next

After a while, you will receive a signed certificate from your Certificate Authority in PEM (Privacy-Enhanced Mail) format. Save the body of the message (and just the body) in a file called "certfile.pem" and place it and the "keyfile.pem" file into the "./servers/servername/modules/nsssl/" directory. Edit your nsd.tcl file to load nsssl.so (or nsssle.so), and verify the location of these two files in the "ns/server/servername/module/nsssl" section.

That's it! You're all set and ready to use the SSL v2 protocol to provide secure access to your web site!

Security Notes

Due to export, patent, and intellectual property issues with RSA, RC4, RC2, and some other algorithms, the 40-bit/512-bit export version is the only binary of nsssl that America Online is permitted to distribute from http://aolserver.com/. If you wish to use the 128-bit/1024-bit domestic version of nsssl, you will have to obtain RSA BSAFE 3 libraries from http://www.rsa.com/ and build nsssl on your own. Unfortunately, we are forbidden to distribute a binary build of nsssl with 128-bit/1024-bit domestic encryption for the reasons stated above. We are permitted to distribute a binary build with 40-bit/512-bit encryption, and we are also allowed to distribute the nsssl source code itself.

The "keyfile.pem" is a very sensitive document! Do not let it out of your hands, do not send it out over the network, and don't delete it. It contains your server's private key and if it's lost then you must cancel your certificate, regenerate the key pair, and get it signed all over again. You should put this in the "./servers/servername/modules/nsssl/" directory.

The "certreq.pem" file generated by keygen.tcl should be deleted once you receive your signed certificate, but it's harmless (but useless) to keep around.

The "certfile.pem" file that you will receive from the certificate authority is very valuable, though it can be handled in a less-secure fashion. You put this in the "./servers/servername/modules/nsssl/" directory.

Implementation Notes

nsssl vs. nssock

If you are familiar with the AOLserver socket driver "nssock," you may notice that the driver-related portions of nsssl are almost identical. In fact, they are so alike that nsssl will eventually merge back into the nssock driver with #ifdefs to enable SSL. This eliminates lots of duplicated code and should eliminate version skew if nssock and the AOLserver socket driver API change over time.

Running AOLserver in Stand-Alone Mode

What's this about running AOLserver just to source a Tcl script? This was an interesting exercise in using Tcl's extensible C API to load dynamic objects. The old nsssl module for AOLserver 2.x used the old web-based admin interface with lots of Tcl code bound to URL's with ns_register_proc. Partly because of this design, nsssl's key, certificate, and x.509 handling is a mixture of C and Tcl code. Since the code as a whole is functional, duplicating the same nsssl code into an external executable seemed silly.

There are three entry points in nsssl:
Ns_ModuleInit -- for AOLserver's dynamic loader
Nsssle_Init -- for Tcl's dynamic loader (export version)
Nsssl_Init -- for Tcl's dynamic loader (domestic version)

o When AOLserver starts up as a normal web server, it invokes Ns_ModuleInit which starts up the socket driver and initializes SSL. The only Tcl command registered is "ssl_info," a meek version-reporting function.
o When AOLserver starts up with ./modules/nsssl/keygen.tcl, the Tcl "load" command this file asks the Tcl interpreter to load nsssl.so (or nsssle.so) and invoke Nsssl_Init (or Nsssle_Init) which registers special key/cert generation Tcl commands and initializes SSL, but doesn't start up the socket library. When the keygen.tcl script is finished, it terminates the server and returns.
In this fashion way we can use the same code for serving pages as well as generating the key pair and certificate request without having another cumbersome binary executable hanging around.