README
SYNOPSIS

 This Apache module provides strong cryptography for the Apache 2.4 webserver
 via the Secure Sockets Layer (v3) and Transport Layer Security (TLS
 v1) protocols by the help of the SSL/TLS implementation library NSS

 This module is based heavily on the mod_ssl package. In fact, it's more
 a conversion than anything else.

BUILDING

 To build this you'll need NSPR 4.9.+ and NSS 3.14.+. It may work with earlier
 versions but these are recommended (or tested). These can be retrieved from
 http://www.mozilla.org/. The --with-nspr and --with-nss tags require that
 the package be installed in the same parent directory (e.g. /opt/nspr,
 /usr/local/nspr, etc). It will look in this parent for include/, lib/, etc.

 If --with-nss or --with-nspr are not passed configure will look for the
 mozilla-[nss|nspr]-devel packages and use the libraries with that if found.
 It is strongly recommended that the mozilla.org version be used instead.

 Build and install those packages somewhere then configure the module with
 something like:

 % autoreconf -ivf
 % ./configure --with-apxs[=/path/to/apxs/] --with-nspr=/path/to/nspr/ --with-nss=/path/to/nss/
 % gmake all install

 You only need to use =/path/to/apxs if apxs isn't in your path or if you
 want to install into a specific Apache installation.

 This will install a sample configuration file nss.conf. You'll need to do
 some hand-editing as well to tell Apache to read this file.

 To httpd.conf add (anywhere is fine):

 Include conf/nss.conf

 You'll need to change the default ports in nss.conf from 443 to
 something else if you aren't starting the server as root.

CONFIGURING NSS

 You'll need to create an NSS database and get a server certificate installed.
 A script, gencerts, is included to help get things going with a self-signed
 certificate. This is a *BAD* idea and you shouldn't use this. It is for
 demonstration purposes only. As a matter of policy, users should not get
 used to accepting a SSL certifiate signed by an unknown or untrusted
 issuer.

 The result of the gencert script is an NSS database that contains a
 self-signed CA, a server certificate (nickname Server-Cert) and a
 client certificate (alpha). The client certificate is generated to make
 testing client authentication simpler.

 You can store the token passwords in a file so you aren't prompted during
 startup (so you can do unattended starts, for example). To do this, set
 the file that will store the token passwords in the NSSPassPhraseDialog 
 attribute in nss.conf ala:

 NSSPassPhraseDialog  file:/path/to/password.conf

 The format of the file for a non-hardware token is tokenname:password.
 A sample for the internal software token is like:

 internal:netscape

BUILT-IN ROOT CAs

NSS provides a list of built-in CA's (VeriSign, Thawte, etc). This takes the
form of a shared library, libnssckbi.so. If this library is placed in the
same directory as the certificate database then it will be loaded
automatically when the server starts.

DOCUMENTATION

 See docs/mod_nss.html for additional information.

 For NSS documentation, see http://www.mozilla.org/projects/security/pki/nss/

REQUESTING A CERTIFICATE

 You can use the provided gencert utility as a template for generating a
 CA and a sample user and server certificate. Alterntaively, the NSS
 command-line tools may be used to generate a certificate request
 suitable for submission to a local CA or a commerical CA like Verisign,
 and install the issued certificate into your local database. A sample
 request may look something like this. This assumes that your certificate
 database directory (NSSCertificateDatabase) is set to /etc/httpd/alias

 Step 1 Create the database. This assumes you want your certificate database
        in /etc/httpd/alias

 % cd /etc/httpd
 % mkdir alias
 % cd alias
 % certutil -N -d .

 Step 2 Generate a PKCS#10 certificate request

 % certutil -R -d . -s "CN=test.example.com, O=Example, c=US" -o certreq.txt -a

 The file certreq.txt contains an ASCII representation of the certificate
 request and may be submitted to a CA for approval.

 Step 3 The CA has issued your certificate. In this example, you have the
        PKCS#7 (ASCII) copy in the file cert.txt. You have a copy of the CA
        certificate chain in ca.txt.

 % certutil -A -d . -n Server-Cert -t "u,u,u" -a < cert.txt 
 % certutil -A -d . -n "My CA" -t "CTu,CTu,CTu" -a < ca.txt 

 Step 4 Verify that the certificate and CA are installed correctly

 % certutil -V -u V -d . -n Server-Cert

TESTING

 A few simple scripts are provided to stand up an in-tree Apache instance
 against which some basic tests can be run to validate that the in-tree
 library works.

 The following dependencies are needed to run the tests:
  python-nose
  python-requests
  python-ndg_httpsclient

 From the source tree run:

 % make check

 The tests are run twice. Once with the old-style database and once
 using the sqlite database format. See
 https://wiki.mozilla.org/NSS_Shared_DB

 This is controlled by the environment variable DBPREFIX which needs
 to be set to sql: when using the newer format for the tests.

 A test for the OpenSSL-compatibility is also executed. It tries to
 compare the output of `openssl ciphers <string>` with the
 equivalent from mod_nss. This may vary by release of OpenSSL and
 what ciphers are available in NSS.

 The test suite requires python >= 2.7.10 and
 python-requests > 2.7.0.

 There is a very small SNI suite included as well. To run it you
 need to add www[1..25].example.com to your /etc/hosts pointing
 to your IP address. Then run:

 % make checksni