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
IntroductionThe nsssl driver supports SSL v2 according to the Netscape SSL documentation, which you can find at http://developer.netscape.com/. It was developed using the BSAFE 3 libraries from RSA Data Security at http://www.rsa.com/.
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!
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.
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:
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