$Header: /cvsroot/aolserver/nsopenssl/README,v 1.6 2004/08/25 21:33:47 dossy Exp $

SSLv2, SSLv3, TLSv1 Module
--------------------------

This module requires OpenSSL 0.9.6 or higher. This module also
requires that you use nsd8x, not nsd76.


Feature Highlights
------------------

 * Open Source software (AOLserver Public License or GPL)
 * Useable for both commercial and non-commercial use
 * 128-bit strong cryptography world-wide
 * Support for SSLv2, SSLv3 and TLSv1 protocols
 * Support for both RSA and Diffie-Hellman ciphers
 * Support for client certificate verification
 * Clean, reviewable ANSI C source code

Troubleshooting nsopenssl
-------------------------
If the key for your certificate won't load, it may be protected by
a passphrase. You can tell by looking at it. If you see something
like:

  -----BEGIN RSA PRIVATE KEY-----
  Proc-Type: 4,ENCRYPTED
  DEK-Info: DES-CBC,C19C9EF4C9122A23

  D3kU+2NbhHs+BYG8vEljim0aoqYjGbbcSR1i+1KM4753FTLfJBCNWSBha+m18pLO
  U2erWwNLLyAWH2bxVKJDedKE3Hpr2TAq1R43s5heSP4YqGITAWMiknRHJm9f86ZA
  ...

then the key is passphrase-protected.

An unprotected key will begin like this:

  -----BEGIN RSA PRIVATE KEY-----
  MIICXQIBAAKBgQCdLzpBdFeAuOadJbWBkWob1GOwGl0BQhub2zucE9qXjzpCFcjK
  Z6gOO6rsj1DiHmSHxlGY3jWK7FFiGuTFHW1BxsAi7IBjAPdqm/g52WgP0g3JQBpE
  ...


Compiling the code
------------------

To compile this code, just type:

gmake OPENSSL=/usr/local/ssl

or:

export OPENSSL=/usr/local/ssl
gmake
gmake install INST=/usr/local/aolserver


**** NOTE: Solaris Users:

You may have to add an extra library search path and the gcc library
for the linker to work. Specifically, you may need to change this:

MODLIBS  =  -L$(OPENSSL) -lssl -lcrypto \

to something like this:

MODLIBS  =  -L$(OPENSSL) -lssl -lcrypto \
 -L/usr/local/lib/gcc-lib/sparc-sun-solaris2.6/2.8.1 -lgcc

Adjust for which version of Solaris and GCC you're using.
Much thanks to Ron Patterson, ron.patterson@corp.usa.net, for
this information.


See nsd.tcl for a sample configuration that uses SSL on port 8443.

To test the server, put the sample configuration from nsd.tcl into
your server's nsd.tcl, copy the sample *.pem files to
$INST/servers/server1/modules/nsopenssl, and start your server.  Visit
https://hostname:8443/.

The default key and certificate for the non-existent 'SnakeOil'
company are included for testing purposes. Do not use these on a real
server -- they are for testing only.


Development Environment
-----------------------

The code was developed under Debian 2.2 with OpenSSL 0.9.6. It will
probably run on different flavors of UNIX, though minor modifications
may be necessary.

You can see debug output by putting the server itself in debug
mode. There isn't a separate debug option for nsopenssl, but you can
turn on Trace to see the handshaking in action as clients connect.

OpenSSL must be compiled as position-independent, but it does not
build that way in the configuration that comes from the OpenSSL
distribution.  The OpenSSL 0.9.5a release doesn't appear to have an
option for this so you'll have to include it in your compile step.

gmake CC="gcc -fPIC"

In addition, some operating systems (Solaris x86) may not support
position-independent code that has inline assembler.  The
configuration that seems to work on these platforms is:

./config no-asm
Then, followed by the same gmake step as before:
gmake CC="gcc -fPIC"


Configuration Options
---------------------

For nsopenssl 3.x, AOLserver 4.x:

ns_section "ns/server/${vs1_servername}/module/nsopenssl/sslcontexts"
ns_param vs1_users_ctx        "SSL context used for regular user access"
ns_param vs1_admins_ctx       "SSL context used for administrator access"
ns_param vs1_client_ctx       "SSL context used for outgoing script socket connections"

ns_section "ns/server/${vs1_servername}/module/nsopenssl/defaults"
ns_param server               vs1_users_ctx
ns_param client               vs1_client_ctx

ns_section "ns/server/${vs1_servername}/module/nsopenssl/sslcontext/vs1_users_ctx"
ns_param Role                  server
#ns_param ModuleDir             /path/to/dir
ns_param CertFile              server/server.crt
ns_param KeyFile               server/server.key
ns_param CADir                 ca-client/dir
ns_param CAFile                ca-client/ca-client.crt
ns_param Protocols             "SSLv3, TLSv1"
ns_param CipherSuite           "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:++EXP"
ns_param PeerVerify            false
ns_param PeerVerifyDepth       3
ns_param Trace                 true

ns_section "ns/server/${vs1_servername}/module/nsopenssl/sslcontext/vs1_admins_ctx"
ns_param Role                  server
#ns_param ModuleDir             /path/to/dir
ns_param CertFile              server/server.crt
ns_param KeyFile               server/server.key
ns_param CADir                 ca-client/dir
ns_param CAFile                ca-client/ca-client.crt
#ns_param Protocols             "All"
ns_param Protocols             "SSLv3, TLSv1"
ns_param CipherSuite           "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:++EXP"
ns_param PeerVerify            false
ns_param PeerVerifyDepth       3
ns_param Trace                 true

# SSL drivers. Each driver defines a port and a named SSL context to associate
# with it.

ns_section "ns/server/${vs1_servername}/module/nsopenssl/ssldrivers"
ns_param vs1_users_drv            "Driver for vs1 regular user access"
ns_param vs1_admins_drv           "Driver for vs1 administrator access"

ns_section "ns/server/${vs1_servername}/module/nsopenssl/ssldriver/vs1_users_drv"
ns_param sslcontext            vs1_users_ctx
ns_param port                  7001
ns_param hostname              $hostname
ns_param address               $address

ns_section "ns/server/${vs1_servername}/module/nsopenssl/ssldriver/vs1_admins_drv"
ns_param sslcontext            vs1_admins_ctx
ns_param port                  7002
ns_param hostname              $hostname
ns_param address               $address

#
# Modules to load
#
ns_section "ns/server/${vs1_servername}/modules"
ns_param   nssock          ${bindir}/nssock${ext}
ns_param   nslog           ${bindir}/nslog${ext}
ns_param   nscgi           ${bindir}/nscgi${ext}
ns_param   nsopenssl       ${bindir}/nsopenssl${ext}
For versions prior to 2.x:

ns_section "ns/server/${servername}/module/nsopenssl"
ns_param port                     $httpsport
ns_param hostname                 $hostname
ns_param address                  192.168.0.2  # will use global address param if this isn't set here
ns_param CertFile                 certfile.pem
ns_param KeyFile                  keyfile.pem
ns_param Protocols                All
#ns_param Protocols                "SSLv2,SSLv3, TLSv1, all"
#ns_param CipherSuite              "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"
#ns_param SessionCache		   false
#ns_param SessionCacheSize         512
#ns_param SessionCacheTimeout      300
ns_param ClientVerify             true
ns_param CADir                    ca
ns_param CAFile                   ca.pem 
ns_param Trace                    false
ns_param RandomFile               /some/file
ns_param SeedBytes                1024


For nsopenssl 2.x, AOLserver 3.x:
----------------------------------------------------------------
ns_section "ns/server/${servername}/module/nsopenssl"

# NSD-driven connections:
ns_param ServerPort                      $httpsport
ns_param ServerHostname                  $hostname
ns_param ServerAddress                   $address
ns_param ServerCertFile                  certfile.pem
ns_param ServerKeyFile                   keyfile.pem
ns_param ServerProtocols                 "SSLv2, SSLv3, TLSv1"
ns_param ServerCipherSuite               "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"
ns_param ServerSessionCache              false
ns_param ServerSessionCacheID            1
ns_param ServerSessionCacheSize          512
ns_param ServerSessionCacheTimeout       300
ns_param ServerPeerVerify                true
ns_param ServerPeerVerifyDepth           3
ns_param ServerCADir                     ca
ns_param ServerCAFile                    ca.pem
ns_param ServerTrace                     false

# For listening and accepting SSL connections via Tcl/C API:
ns_param SockServerCertFile              certfile.pem
ns_param SockServerKeyFile               keyfile.pem
ns_param SockServerProtocols             "SSLv2, SSLv3, TLSv1"
ns_param SockServerCipherSuite           "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"
ns_param SockServerSessionCache          false
ns_param SockServerSessionCacheID        2
ns_param SockServerSessionCacheSize      512
ns_param SockServerSessionCacheTimeout   300
ns_param SockServerPeerVerify            true
ns_param SockServerPeerVerifyDepth       3
ns_param SockServerCADir                 internal_ca
ns_param SockServerCAFile                internal_ca.pem
ns_param SockServerTrace                 false

# Outgoing SSL connections
ns_param SockClientCertFile              clientcertfile.pem
ns_param SockClientKeyFile               clientkeyfile.pem
ns_param SockClientProtocols             "SSLv2, SSLv3, TLSv1"
ns_param SockClientCipherSuite           "ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"
ns_param SockClientSessionCache          false
ns_param SockClientSessionCacheID        3
ns_param SockClientSessionCacheSize      512
ns_param SockClientSessionCacheTimeout   300
ns_param SockClientPeerVerify            true
ns_param SockServerPeerVerifyDepth       3
ns_param SockClientCADir                 ca
ns_param SockClientCAFile                ca.pem
ns_param SockClientTrace                 false

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


And to load the module:

ns_section "ns/server/${servername}/modules"
ns_param nsopenssl    ${bindir}/nsopenssl.${ext}


Configuration Notes
-------------------

Session caching is turned on by default.

RandomFile isn't necessary, but if you want to use your own random
bits, you can set this. On Linux, it won't matter: OpenSSL will use
/dev/urandom to transparently seed the PRNG.

SeedBytes is optional; it tells how many bytes to seed the PRNG with, but
only if the PRNG actually needs seeding. It defaults to 1024 bytes. If
seeding the PRNG fails, bump this number up.

WARNING!!! If the client sends an invalid certificate, the connection
is still accepted. Use 'ns_openssl clientcert valid' in your Tcl code or ADP
page to determine if you received a client certificate and if it was
valid.

NOTE: Your key.pem file must *not* be protected by a passphrase or the server
won't start.


Tcl Interface Commands
----------------------

ns_openssl info
  - returns a Tcl list containing the SSL libary name, SSL library version,
    Crypto library name, Crypto library version.

ns_openssl protocol
  - returns the protocol used by the current connection as a string: 
    SSLv2, SSLv3, TLSv1 or UNKNOWN

ns_openssl cipher name
  - returns the name of the cipher being used by the current connection
    (e.g. RSA_MD5)

ns_openssl cipher strength
  - returns the strength of the cipher being used by the current connection
    as a number (e.g. 40, 56, 128 etc.)

ns_openssl clientcert exists
  - returns 0 if no client certificate exists, or a 1 if a client
    certificate does exist.

ns_openssl clientcert valid
  - returns 1 if client certificate was obtained *and* it is valid; 0 otherwise.

ns_openssl clientcert version
  - returns a Tcl string containing the certificate's version number, e.g. "3".

ns_openssl clientcert serial
  - returns a Tcl string containing the certificate's serial number, e.g. "27C6".

ns_openssl clientcert subject
  - returns a Tcl string containing the certificate's subject name,
    e.g. "/C=US/O=U.S. Government/OU=DoD/OU=PKI/OU=USAF/CN=Goodwin.Scott.S.0300074002"

ns_openssl clientcert issuer
  - returns a Tcl string containing the certificate's issuer name,
    e.g. "/C=US/O=U.S. Government/OU=DoD/OU=PKI/CN=Med CA-2"

ns_openssl clientcert notbefore
  - returns a Tcl string containing the certificate's valid start date,
    e.g. "Aug 28 20:00:38 2000 GMT"

ns_openssl clientcert notafter
  - returns a Tcl string containing the certificate's valid end date,
    e.g. "Aug 28 20:00:38 2002 GMT"

ns_openssl clientcert signature_algorithm
  - returns a Tcl string containing the algorithm used for the signature,
    e.g. "sha1WithRSAEncryption"

ns_openssl clientcert key_algorithm
  - returns a Tcl string containing the algorithm used for the key,
    e.g. "rsaEncryption"

ns_openssl clientcert pem
  - returns a Tcl string containing the client's PEM-formatted certificate,
    which should have "--- BEGIN CERTIFICATE ---" and
    "--- END CERTIFICATE ---" lines in it.


New Commands in 2.0:

ns_openssl_sockopen hostname port
  - opens an SSL connection to the host on the specified port.

ns_openssl_socklisten 
  - listens for SSL connections from clients

ns_openssl_sockaccept 
  - accepts SSL connections from clients

ns_openssl_sockcallback 
  - run a script when the SSL socket is in a certain state

ns_openssl_socklistencallback 
  - listen for SSL connections and run a script when a client connects

ns_httpsget 
  - grab a page from an SSL server

ns_httpsopen 
  - open an SSL connection to a server

ns_openssl_geturl 
  - grab a page from an SSL server


To use the last three commands, you'll need to have https.tcl installed in
your server's module/tcl directory.


Copyright Notices
-----------------

The nsopenssl module was originally written and Copyrighted by Stefan
Arentz. Parts of it are also copyrighted by Scott S. Goodwin. It is
distributed under the AOLserver Public License. See the file
license.txt for more information.

This product includes software developed by the OpenSSL Project for
use in the OpenSSL Toolkit. (http://www.openssl.org/)

This product links to cryptographic software (OpenSSL) originally
written by Eric Young (eay@cryptsoft.com). There is no cryptographic
software within the source code of this module.


Related Links
-------------

  http://scottg.net         Information on AOLserver and this module
  http://www.opennsd.org    OpenNSD site
  http://www.aolserver.com  AOLserver homepage
  http://www.openssl.org    OpenSSL toolkit homepage
  http://www.modssl.org     OpenSSL module for Apache
  http://www.thawte.com     For getting test certificates


Developers
----------

If you make any mods to nsopenssl and commit them, please be sure to
tag after your commit. This allows anyone to go and get a named (i.e.
tagged) snapshot of the code.

You tag by doing:

cvs -q tag nsopenssl-2_2_beta_1

Make sure you know what the latest tag is and increment accordingly.


Design
------

The nsopenssl 3.x series is designed to be more modular. The three main
data types of the module (SSL contexts, Drivers and Connections) are
decoupled. SSL contexts can be created and initialized at any time
and then used with Drivers and Connections. See nsopenssl.h for details.

The process flow is as follows:

     - initialize OpenSSL and 'global' items from nsd.tcl
     - for each virtual server:
        - initialize SSL contexts defined in nsd.tcl
        - create drivers that are defined in nsd.tcl, tying them to an
          SSL context
     - Wait for incoming connections for core HTTP processing, and make
       available a C and Tcl API for creating new SSL contexts, initiating
       SSL listeners and initiating outgoing SSL connections