From 505e42a4b8a735021cbc914b9c08f7aacbeece51 Mon Sep 17 00:00:00 2001 From: rcritten <> Date: Fri, 3 Jun 2005 15:39:54 +0000 Subject: Basic documentation on the mod_nss module. --- docs/mod_nss.html | 908 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 908 insertions(+) create mode 100644 docs/mod_nss.html (limited to 'docs') diff --git a/docs/mod_nss.html b/docs/mod_nss.html new file mode 100644 index 0000000..cffd7f5 --- /dev/null +++ b/docs/mod_nss.html @@ -0,0 +1,908 @@ + + + + + mod_nss + + +

mod_nss

+

Table of Contents

+Introduction
+Building
+Installation
+Certificate Generation
+Server Startup
+Migration
+Configuration Directives
+Environment Variables
+
+

Introduction

+The mod_ssl package was +created in April 1998 by Ralf S. +Engelschall and was originally derived from the Apache-SSL package developed by Ben Laurie. It stays under a +BSD-style +license which is equivalent to the license used by The Apache Group for the Apache +webserver +itself. This means, in short, that you are free to use it both for +commercial +and non-commercial purposes as long as you retain the authors' +copyright +notices and give the proper credit. +
+
+mod_nss is based directly on the mod_ssl package from Apache +2.0.54.  It is a conversion from using OpenSSL calls to using NSS +calls instead.
+

Building

+Refer to the README file included with the distribution.
+
+ To build you'll need NSPR 4.4.1 or above and NSS 3.9.2 or above. +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 options 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/ and +lib/, etc.
+
+Run the configure script. The following mdo_nss-specificoptions are +available:
+
+ + + + + + + + + + + + + + + + + + + +
Option
+ 		Description
+
--with-nss=[PATH]
+ 		The file system path to the NSS +installation. The assumption is that this has the layout of: PATH/lib, +PATH/include, etc.
+
--with-nspr=[PATH]
+ 		The file system path of the NSPR +installation. The assumption is that this has the layout of: PATH/lib, +PATH/include, etc.
--with-apxs=[PATH]
+ 		The location of the apxs binary +of the Apache you want to install the module into.
+
+
+ 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.
+
+ Build and install those packages somewhere then configure the +module with something like:
+
+ % ./configure --with-apxs=/path/to/apxs/ +--with-nspr=/path/to/nspr/ --with-nss=/path/to/nss/
+ % gmake
+
+ This will create a sample configuration file nss.conf. +By default +this is installed during the installation process.
+

Installation

+The make install target uses apxs to install the module into Apache. +This automatically copies the mod_nss shared library to the appropriate +location and updates Apache's httpd.conf so that the module will be +loaded during the next restart.
+
+It also tries to rename ssl.conf to ssl.conf.old.  +The assumption is that mod_nss is replacing mod_ssl. They can co-exist +as long as they are listening on separate ports.
+
+The mod_nss configuration file, nss.conf, is copied into +the Apache +configuration directory (as reported by apxs). You may need to make a +manual change to httpd.conf to load this file. If you have a Red +Hat-style Apache installation with a conf.d just move nss.conf there. +It will be automatically loaded. Otherwise you will need to add the +following line to httpd.conf:
+
+Include nss.conf
+
+This has Apache load the mod_nss configuration file, nss.conf. +It is here that you will setup your VirtualServer entries to and +configure your SSL servers.
+

Certificate Generation

+A ksh script, gencert, is included to automatically +generate a self-signed CA plus one server certificate. This is fine for +testing purposes but it is strongly recommended that a real server +certificate be obtained from a real CA before moving a mod_nss server +into production. Users should be expected to cancel any request to a +secure server signed by an unknown issuer.
+
+gencert takes one argument, the path to the location of +the certificate database. A fair amount of output is generated so you +can follow what is going on. For the most part most don't need to +bother with the details.
+
+The certificate database password is httptest.
+
+A sample run is:
+
+% ./gencert /etc/httpd/nss
+
+#####################################################################
+Generating new server certificate and key database. The password
+is httptest
+#####################################################################
+
+#####################################################################
+Generating self-signed client CA certificate
+#####################################################################
+
+Generating key.  This may take a few moments...
+
+[ Lots of output removed ]
+
+You should now have the following files:
+
+/etc/httpd/nss/cert8.db
+/etc/httpd/nss/key3db
+/etc/httpd/nss/secmod.db
+
+These 3 files make up an NSS certificate database.
+

Server Startup

+Starting a mod_nss server is no different than starting a mod_ssl +server. You will need to authenticate yourself to the security token +(e.g. enter the key password). The sample nss.conf is not included in +an <IfDefine SSL> so you do not need to use the +startssl argument with apachectl.
+
+A sample startup might look like:
+
+% apachectl start
+Please enter password for "internal" token:
+
+If you have additional hardware tokens you will be prompted for each +token password.
+
+All other output will be written to the Apache log files.
+

Migration

+A perl script, migrate,pl, is included to help migrate an +existing mod_ssl configuration to work with mod_nss. There is one +optional argument, -c, that will try to convert your existing server +and CA certificates plus any certificate revocation lists (CRLs) into +an NSS certificate database.
+
+The migration script assumes that you are migrating from ssl.conf to +nss.conf. The original file is not changed. All comments, spacing and +other directives are maintained so if there is no ssl.conf it is +possible to migrate httpd.conf to use mod_nss. Simply copy httpd.conf +to ssl.conf, run the update, then copy nss.conf to httpd.conf (after +making a backup, of couse). This multi-step process gives you a chance +to verify that the migration was successful.
+

Configuration Directives

+The following mod_ssl Directives are not applicable to mod_nss:
+ +SSLPassPhraseDialog
+
+Authentication is required in order to use the private key in an NSS +certificate database. The method of this authentication is specified +with the SSLPassPhraseDialog directive.  This directive takes one +argument specifying the method of authentication:
+ +
The user will be prompted to enter the +token password for each cryptographic device. This works seemlessly +with any hardware tokens used. The default "device" is the internal +token provided by the NSS Certificate database itself.
+
+ +
The token password(s) may be stored in +an ASCII text file which is read during startup so the server can start +without user intervention. The format of this file is:
+
+
token:password
+
+
+
+
An example for the internal token is:
+
+
+
internal:secret12
+
+
+Example
+
+SSLPassPhraseDialog builtin
+

+
+SSLPassPhraseHelper
+
+When Apache starts it loads and unloads any modules that aren't +built-in twice. It loads them once so it can verify that the +configuration is ok and then it unloads them and re-loads them again +when the server is actually ready to receive connections. After the +first module load Apache closes access to the terminal so there is no +way to prompt for the NSS token passwords (it would also be annoying to +have to authenticate twice). Because the module is loaded and unloaded +the NSS certificate database needs to be loaded and unloaded as well, +causing any pins entered during the first load to be lost and causing +the server to be unstartable.
+
+The solution is the PassPhraseHelper. This is a stand-alone program +that also opens the NSS certificate database and stores a copy of the +encrypted token password entered during the first load of the NSS +module. When mod_nss needs to open the certificate database during +subsequent reloads it queries the PassPhraseHelper for the token +password.
+
+Example
+
+SSLPassPhraseHelper /path/to/nss_pcache
+
+SSLCertificateDatabase
+
+Specifies the location of the NSS certificate database to be used. An +NSS certificate database consists of 3 files: cert8.db, key3.db and +secmod.db. cert8.db stores certificates and Certificate Revocation +Lists (CRLs), key3.db stores keys and secmod.db stores information +about available pkcs#11 modules.
+
+This directive specifies a path, not a filename.
+
+Example
+
+SSLCertificateDatabase /etc/httpd/conf/nss
+
+SSLSessionCacheSize
+
+Specifies the number of SSL sessions that can be cached.
+
+There is no upper limit.
+
+The default value is 10000.
+
+Example
+
+SSLSessionCacheSize 10000
+
+SSLSessionCacheTimeout
+
+Specifies the number of seconds SSL2 sessions are cached.
+
+The valid range is 5 - 100 seconds. A setting outside the valid range +is silently constrained.
+
+The default value is 100.
+
+Example
+
+SSLSessionCacheTimeout 100
+
+SSL3SessionCacheTimeout
+
+Specifies the number of seconds SSL3 sessions are cached.
+
+The valid range is 5 - 86400 seconds.  A setting outside the valid +range is silently constrained.
+
+The default value is 86400 (24 hours).
+
+Example
+
+SSL3SessionCacheTimeout 86400
+
+SSLEngine
+
+Enables or disables the SSL protocol. This is usually used within a +VirtualHost tag to enable SSL for a particular virtual host.
+
+SSL is disabled by default.
+
+Example
+
+SSLEngine on
+
+SSLCipherSuite
+
+A space-separated list of the SSL ciphers used, with the prefix + +to enable or - to disable.
+
+All ciphers are disabled by default.
+
+Available ciphers are:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Cipher Name
+ 		NSS Cipher +definition
+ 		Protocol
+
des
+ 		SSL_EN_DES_64_CBC_WITH_MD5
+ 		SSLv2
desede3
+ 		SSL_EN_DES_192_EDE3_CBC_WITH_MD5
+ 		SSLv2
rc2
+ 		SSL_EN_RC2_128_CBC_WITH_MD5
+ 		SSLv2
rc2export
+ 		SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5
+ 		SSLv2
rc4
+ 		SSL_EN_RC4_128_WITH_MD5
+ 		SSLv2
rc4export
+ 		SSL_EN_RC4_128_EXPORT40_WITH_MD5
+ 		SSLv2
rsa_3des_sha
+ 		SSL_RSA_WITH_3DES_EDE_CBC_SHA
+ 		SSLv3/TLSv1
+
rsa_des_sha
+ 		SSL_RSA_WITH_DES_CBC_SHA
+ 		SSLv3/TLSv1
rsa_null_md5
+ 		SSL_RSA_WITH_NULL_MD5
+ 		SSLv3/TLSv1
rsa_null_sha
+ 		SSL_RSA_WITH_NULL_SHA
+ 		SSLv3/TLSv1
rsa_rc2_40_md5SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
+ 		SSLv3/TLSv1
rsa_rc4_128_md5SSL_RSA_WITH_RC4_128_MD5
+ 		SSLv3/TLSv1
rsa_rc4_128_shaSSL_RSA_WITH_RC4_128_SHA
+ 		SSLv3/TLSv1
rsa_rc4_40_md5SSL_RSA_EXPORT_WITH_RC4_40_MD5
+ 		SSLv3/TLSv1
fortezza
+ 		SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA
+ 		SSLv3/TLSv1
fortezza_rc4_128_sha
+ 		SSL_FORTEZZA_DMS_WITH_RC4_128_SHA
+ 		SSLv3/TLSv1
fortezza_null
+ 		SSL_FORTEZZA_DMS_WITH_NULL_SHA
+ 		SSLv3/TLSv1
fips_des_sha
+ 		SSL_RSA_FIPS_WITH_DES_CBC_SHA
+ 		SSLv3/TLSv1
fips_3des_sha
+ 		SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
+ 		SSLv3/TLSv1
rsa_des_56_shaTLS_RSA_EXPORT1024_WITH_DES_CBC_SHA
+ 		SSL3/TLSv1
rsa_rc4_56_shaTLS_RSA_EXPORT1024_WITH_RC4_56_SHA
+ 		SSLv3/TLSv1
rsa_aes_128_sha
+ 		TLS_RSA_WITH_AES_128_CBC_SHA
+ 		SSLv3/TLSv1
rsa_aes_256_sha
+ 		TLS_RSA_WITH_AES_256_CBC_SHA
+ 		SSLv3/TLSv1
+
+Example
+
+SSLCipherSuite +-des,-desede3,-rc2,-rc2export,-rc4,-rc4export,+rsa_3des_sha,-rsa_des_56_sha,
++rsa_des_sha,-rsa_null_md5,-rsa_null_sha,-rsa_rc2_40_md5,+rsa_rc4_128_md5,-rsa_rc4_128_sha,
+-rsa_rc4_40_md5,-rsa_rc4_56_sha,-fortezza,-fortezza_rc4_128_sha,-fortezza_null,-fips_des_sha,
++fips_3des_sha,-rsa_aes_128_sha,-rsa_aes_256_sha
+
+SSLProtocol
+
+A comma-separated string that lists the basic protocols that the server +can use (and clients may connect with). It doesn't enable a cipher +specifically but allows ciphers for that protocol to be used at all.
+
+Options are:
+ +Note that this differs from mod_ssl in that you can't add or subtract +protocols.
+
+Example
+
+SSLProtocol SSLv3,TLSv1
+
+SSLNickname
+
+Specify the nickname to be used for this the server certificate. +Certificates stored in an NSS database are referred to using nicknames +which makes accessing a specific certificate much easier. It is also +possible to specify the certificate DN but it is easier to use a +nickname.
+
+Example
+
+SSLNickname Server-Cert
+
+SSLVerifyClient
+
+Determines whether Client Certificate +Authentication will be requested or required. This may be set in a +per-server or per-directory context. At the server level the +certificate is requested during the initial SSL handshake. In the +per-directry context an SSL renogitation is required and a certificate +requested from the client.
+
+Available options are:
+ + +The mod_ssl option option_no_ca +is not supported.
+
+There is no SSLVerifyDepth directive. NSS always verifies +the entire certificate chain.
+
+Example
+
+SSLVerifyClient require
+
+SSLUserName
+
+Defines the field in the client certificate which will set the user +field in the request. The option FakeBasicAuth (see SSLOptions) must +also be set for this to work.
+
+Example
+
+SSLUserName SSL_CLIENT_S_DN_UID
+
+SSLOptions
+
+Control various options in a per-server or per-directory context.
+ +All options are disabled by default.
+
+Example:
+
+SSLOptions +FakeBasicAuth
+<Files ~ "\.(cgi|shtml)$">
+SSLOptions +StdEnvVars
+<Files> +
+
+SSLRequireSSL
+
+The request is forbidden unless the connection is using SSL. Only +available in a per-directory context. This takes no arguments.
+
+Example
+
+SSLRequireSSL
+
+SSLRequire
+
+Provides a regular expression-based access-control mechanism. Access +may be restricted (or allowed) based on any number of variables such as +components of the client certificate, the remote IP address, etc.
+
+SSLRequire
+

Environment Variables

+Quite a few environment variables (for CGI and SSI) may be set +depending on the SSLOptions configuration. It can be expensive to set +these so it is recommended that they only be set when they will be used +(e.g. don't set them on a per-server basis). Here is a list of the +variables along with the option used to set them.
+
+

Always Set

+
+ + + + + + + + + + + +
Name
+ 		Description
+
HTTPS
+ 		Set to "on" if HTTPS is being +used
+
+
+
+

+StdEnvVars
+

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name
+ 		Description
+
SSL_VERSION_INTERFACE
+ 		The version of mod_nss the +server is running
+
SSL_VERSION_LIBRARY
+ 		The version of NSS that mod_nss +was compiled against.
+
SSL_PROTOCOL
+ 		SSLv2, SSLv3 or TLSv1
+
SSL_CIPHER
+ 		The cipher the connection is +using
+
SSL_CIPHER_EXPORT
+ 		true if the cipher is an export +cipher, false otherwise
+
SSL_CIPHER_USEKEYSIZE
+ 		Number if bits the cipher is +using
+
SSL_CIPHER_ALGKEYSIZE
+ 		Max number of bits possible in +the cipher
+
SSL_CLIENT_VERIFY
+ 		NONE if no client auth, SUCCESS +or FAILED if SSLVerifyCert is set
+
SSL_CLIENT_V_START
+ 		Client certificate validity +start time
+
SSL_CLIENT_V_END
+ 		Client certificate validity end +time
SSL_CLIENT_M_VERSION
+ 		X.509 version of the client +certificiate
+
SSL_CLIENT_M_SERIAL
+ 		Serial number of the client +certificate
+
SSL_CLIENT_A_KEYAlgorithm used for client key
+
SSL_CLIENT_A_SIGAlgorithm used for the signature +of  the client key
SSL_CLIENT_S_DNDistinguished Name (DN) of the +client certificate
SSL_CLIENT_S_DN_[C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email]
+ 		Components of the client +certificate. Only those that exist in the certificate are created.
+
SSL_CLIENT_I_DN
+ 		Distinguished Name (DN) of the +client certificate issuer
+
SSL_CLIENT_I_DN_[C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email]Components of the client issuer +certificate. Only those that exist in the certificate are created
SSL_SERVER_DN
+ 		Distinguished Name (DN) of the +server certificate
+
SSL_SERVER_DN_[C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email]Components of the server +certificate. Only those that exist in the certificate are created
SSL_SERVER_I_DN_[C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email]Components of the server issuer +certificate. Only those that exist in the certificate are created
SSL_SERVER_M_VERSION
+ 		X.509 version of the server +certificiate
SSL_SERVER_M_SERIAL
+ 		Serial number of the server +certificate
SSL_SERVER_V_START
+ 		Server certificate validity +start time
SSL_SERVER_V_END
+ 		Server certificate validity end +time
SSL_SERVER_A_KEY
+ 		Algorithm used for server key
SSL_SERVER_A_SIG
+ 		Algorithm used for the signature +of  the server key
SSL_SESSION_ID
+ 		SSL Session ID
+
+
+

+ExportCertData
+

+ + + + + + + + + + + + + + + + + + + +
Name
+ 		Description
+
SSL_SERVER_CERT
+ 		The server certificate in PEM +format.
+
SSL_CLIENT_CERT
+ 		The client certificate in PEM +format (if available)
+
SSL_CLIENT_CERT_CHAIN_[0..n]
+ 		Each certificate in the client +certificate chain in PEM format (including the client certificate +itself).
+
+
+Troubleshooting
+
+
+ + -- cgit