
$Header: /cvsroot/aolserver/aolserver3/doc/nsssl2.txt,v 1.1 2000/03/25 22:14:20 kriston Exp $


The nsssl2 Socket Driver
------------------------


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).


The nsssl2 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 initial public release of nsssl2 does
sacrifice completeness for the sake of simplicity and reliability.
For one thing, it only 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
nsssl2.


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/server1/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/server1/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 nsssl2 that America Online is permitted to
distribute from http://aolserver.com/.  If you wish to use the
128-bit/1024-bit domestic version of nsssl2, you will have to obtain
RSA BSAFE 3 libraries from http://www.rsa.com/ and build nsssl2 on
your own.  Unfortunately, we are forbidden to distribute a binary
build of nsssl2 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 nsssl2 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/server1/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/server1/modules/nsssl/"
directory.


Implementation Notes
--------------------

 nsssl2 vs. nssock
 ----------------- 

 If you are familiar with the AOLserver socket driver "nssock," you
 may notice that the driver-related portions of nsssl2 are almost
 identical.  In fact, they are so alike that nsssl2 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.

