mod_nss

Introduction
Building
Installation
Certificate Generation
Server Startup
Migration
Configuration Directives
Environment Variables
Database Management
Why is SSLv2 disabled?
Frequently Asked Questions
Sample Use Cases

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 is licensed under the Apache 2.0 license.

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.

To build with ECC support you need NSPR 4.6.2 or higher and NSS 3.11.2 or higher.

You will also need the NSS and NSPR directories in your library search path (either /etc/ld.so.conf or LD_LIBRARY_PATH) to link and run the module.

Run the configure script. The following mod_nss-specific options 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-nss-inc=PATH	The file system path to the NSS include directory (e.g. /usr/local/include/nss3)
--with-nss-lib=PATH	The file system path to the NSS lib directory (e.g. /usr/local/lib)
--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-nspr-inc=PATH	The file system path to the NSPR include directory (e.g. /usr/local/include/nspr4)
--with-nspr-lib=PATH	The file system path to the NSPR lib directory (e.g. /usr/local/lib)
--with-apxs=[PATH]	The location of the apxs binary of the Apache you want to install the module into.
--with-apr-config=[PATH]	The location of apr-config which tells us where the APR include files and libraries are located
--enable-ssl2	SSLv2 is disabled by default.
--enable-ecc	Enable Elliptical Curve Cryptography. Disabled by default.

If --with-nss or --with-nspr are not passed configure will look for the [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 (location relative to httpd.conf):

Include conf/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:

# mkdir /etc/httpd/nss
# ./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.

To avoid being prompted for a startup password you can either:

Use a password file that contains your token passwords. See NSSPassPhraseDialog for details.
Change the internal token password to a blank with:

% modutil -dbdir /path/to/database/directory -changepw "NSS Certificate DB"

Enter the old password then press Enter twice for the new password to blank it out.

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:

SSLSessionCache
SSLMutex
SSLCertificateChainFile
SSLCARevocationPath
SSLCARevocationFile
SSLVerifyDepth
SSLCryptoDevice

NSSPassPhraseDialog

Authentication is required in order to use the private key in an NSS certificate database. The method of this authentication is specified with the NSSPassPhraseDialog directive. This directive takes one argument specifying the method of authentication:

builtin

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.

file:/path/to/file

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

NSSPassPhraseDialog builtin

NSSPassPhraseHelper

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

NSSPassPhraseHelper /path/to/nss_pcache

NSSCertificateDatabase

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

NSSCertificateDatabase /etc/httpd/conf/nss

NSSDBPrefix

Normally a certificate database consists of 3 files: cert8.db, key3.db and secmod.db. This directive allows you to add a named prefix to the filenames of cert8.db and key3.db so you can store multiple databases in one directory.

Example

NSSDBPrefix my-prefix-

You would then need: my-prefix-cert8.db, my-prefix-key3.db and secmod.db

In order to work with files with a prefix using the NSS command-line tools use the -P flag.

NSSSessionCacheSize

Specifies the number of SSL sessions that can be cached.

There is no upper limit.

The default value is 10000.

Example

NSSSessionCacheSize 10000

NSSSessionCacheTimeout

Specifies the number of seconds SSL 2 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

NSSSessionCacheTimeout 100

NSSSession3CacheTimeout

Specifies the number of seconds SSL 3 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

NSSSession3CacheTimeout 86400

NSSRandomSeed

Configures sources to seed the NSS Random Number Generator (RNG) at startup. Currently this only supports seeding the RNG at startup.

The following sources are available:

builtin: Combines the current system time, the current process id and a randomly choosen 128-byte extract of the process stack. This is not a particularly strong source of entropy.
file:/path/to/source: Reads from the specified file. If the number of bytes to read is specified it just reads that amount. Be aware that some operating systems block on /dev/random if not enough entropy is available. This means that the server will wait until that data is available to continue startup. These systems generally offer a non-blocking device as well, /dev/urandom.
exec:/path/to/program: Executes the given program and takes the stdout of it as the entropy. If the bytes argument is included it reads that many bytes, otherwise it reads until the program exits.

Example

NSSRandomSeed startup builtin

NSSRandomSeed startup /dev/urandom 512

NSSRandomSeed startup /usr/bin/makerandom

NSSEngine

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

NSSEngine on

NSSFIPS

Enables or disables FIPS 140 mode. This replaces the standard internal PKCS#11 module with a FIPS-enabled one. It also forces the enabled protocols to TLSv1.2, TLSv1.1 and TLS v1.0 and disables all ciphers but the FIPS ones. You may still select which ciphers you would like limited to those that are FIPS-certified. Any non-FIPS that are included in the NSSCipherSuite entry are automatically disabled. The allowable ciphers are:

rsa_3des_sha
rsa_des_sha
fips_3des_sha
fips_des_sha
rsa_des_56_sha
fortezza

FIPS is disabled by default.

Example

NSSFIPS on

NSSOCSP

Enables or disables OCSP (Online Certificate Status Protocol). This allows the server to check the validity of a client certificate before accepting it.

OCSP is disabled by default.

Example

NSSOCSP on

NSSCipherSuite

A space-separated list of the SSL ciphers used, with the prefix + to enable or - to disable.

All ciphers are disabled by default. The SSLv2 ciphers cannot be enabled because SSLv2 is not allowed in mod_nss.

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.0/TLSv1.1/TLSv1.2
rsa_des_sha	SSL_RSA_WITH_DES_CBC_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_null_md5	SSL_RSA_WITH_NULL_MD5	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_null_sha	SSL_RSA_WITH_NULL_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_rc2_40_md5	SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_rc4_128_md5	SSL_RSA_WITH_RC4_128_MD5	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_rc4_128_sha	SSL_RSA_WITH_RC4_128_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_rc4_40_md5	SSL_RSA_EXPORT_WITH_RC4_40_MD5	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
fortezza	SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
fortezza_rc4_128_sha	SSL_FORTEZZA_DMS_WITH_RC4_128_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
fortezza_null	SSL_FORTEZZA_DMS_WITH_NULL_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
fips_des_sha	SSL_RSA_FIPS_WITH_DES_CBC_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
fips_3des_sha	SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_des_56_sha	TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_rc4_56_sha	TLS_RSA_EXPORT1024_WITH_RC4_56_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_aes_128_sha	TLS_RSA_WITH_AES_128_CBC_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2
rsa_aes_256_sha	TLS_RSA_WITH_AES_256_CBC_SHA	SSLv3/TLSv1.0/TLSv1.1/TLSv1.2

Additionally there are a number of ECC ciphers:

Cipher Name	NSS Cipher Definition	Protocol
ecdh_ecdsa_null_sha	TLS_ECDH_ECDSA_WITH_NULL_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_ecdsa_rc4_128_sha	TLS_ECDH_ECDSA_WITH_RC4_128_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_ecdsa_3des_sha	TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_ecdsa_aes_128_sha	TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_ecdsa_aes_256_sha	TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_ecdsa_null_sha	TLS_ECDHE_ECDSA_WITH_NULL_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_ecdsa_rc4_128_sha	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_ecdsa_3des_sha	TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_ecdsa_aes_128_sha	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_ecdsa_aes_256_sha	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_rsa_null_sha	TLS_ECDH_RSA_WITH_NULL_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_rsa_128_sha	TLS_ECDH_RSA_WITH_RC4_128_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_rsa_3des_sha	TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_rsa_aes_128_sha	TLS_ECDH_RSA_WITH_AES_128_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_rsa_aes_256_sha	TLS_ECDH_RSA_WITH_AES_256_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
echde_rsa_null	TLS_ECDHE_RSA_WITH_NULL_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_rsa_rc4_128_sha	TLS_ECDHE_RSA_WITH_RC4_128_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_rsa_3des_sha	TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_rsa_aes_128_sha	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdhe_rsa_aes_256_sha	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_anon_null_sha	TLS_ECDH_anon_WITH_NULL_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_anon_rc4_128sha	TLS_ECDH_anon_WITH_RC4_128_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_anon_3des_sha	TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_anon_aes_128_sha	TLS_ECDH_anon_WITH_AES_128_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2
ecdh_anon_aes_256_sha	TLS_ECDH_anon_WITH_AES_256_CBC_SHA	TLSv1.0/TLSv1.1/TLSv1.2

Example

NSSCipherSuite
+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

NSSProtocol

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:

SSLv3
TLSv1 (legacy only; replaced by TLSv1.0)
TLSv1.0
TLSv1.1
TLSv1.2
All

Note that this differs from mod_ssl in that you can't add or subtract protocols.

If no NSSProtocol is specified, mod_nss will default to allowing the use of the TLSv1.0, TLSv1.1 and TLSv1.2 protocols, where TLSv1.0 will be set to be the minimum protocol allowed, and TLSv1.2 will be set to be the maximum protocol allowed.
If values for NSSProtocol are specified, mod_nss will set both the minimum and the maximum allowed protocols based upon these entries allowing for the inclusion of every protocol in-between. For example, if only SSLv3 and TLSv1.1 are specified, SSLv3, TLSv1.0, and TLSv1.1 will all be allowed, as NSS utilizes protocol ranges to accept all protocols inclusively (TLS 1.1 -> TLS 1.0 -> SSL 3.0), and does not allow exclusion of any protocols in the middle of a range (e. g. - TLS 1.0).

Finally, NSS will always automatically negotiate the use of the strongest possible protocol that has been specified which is acceptable to both sides of a given connection.
SSLv2 is not supported by default at this time.

Example

NSSProtocol SSLv3,TLSv1.0,TLSv1.1

NSSNickname

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. If the nickname includes spaces then the value needs to be enclosed in double quotes.

Example

NSSNickname Server-Cert
NSSNickname "This contains a space"

NOTE: There is nothing magical about the string "Server-Cert." A nickname can be anything. Historically this was Server-Cert in the Netscape server products that used NSS.

NSSECCNickname

Similar to NSSNickname but designed for use with ECC certificates. This allows you to have both an RSA certificate and an ECC certificate available on the same listening port. This allows newer clients that support ECC to connect with those ciphers but also allows older clients to connect with an RSA cipher.

Example

NSSNickname Server-Cert-ECC

NSSEnforceValidCerts

By default mod_nss will not start up if the server certificate is not valid. This means that if the certificate has expired or is signed by a CA that is not trusted in the NSS certificate database the server will not start. If you would like the server to start anyway you can add this directive to nss.conf and the server will start with just a warning. Not enforcing a valid server certificate is not recommended.

Example

NSSEnforceValidCerts on

NSSVerifyClient

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:

none: no client certificate is required or requested
optional: a client certificate is requested but if one is not available, the connection may continue.
require: a valid client certificate is required for the connection to continue.

The mod_ssl option option_no_ca is not supported.

There is no NSSVerifyDepth directive. NSS always verifies the entire certificate chain.

Example

NSSVerifyClient require

NSSUserName

Defines the field in the client certificate which will set the user field in the request. The option FakeBasicAuth (see NSSOptions) must also be set for this to work.

Example

NSSUserName SSL_CLIENT_S_DN_UID

NSSOptions

Control various options in a per-server or per-directory context.

FakeBasicAuth: When this option is enabled and NSSUserName is set then the certificate attribute defined in NSSUserName is used to populate the value of r->user in the Apache request object. This equates to the environmant variable REMOTE_USER.
StdEnvVars: A standard set of SSL environment variables is created.
CompatEnvVars: A no-op. In previous versions of mod_ssl this would set additional environment variables for backwards compatibility with older Apache SSL implementations.
ExportCertData: Several additional environment variables are created, SSL_CLIENT_CERT, SSL_CLIENT_CERT_CHAIN[0..n] andSSL_SERVER_CERT. This provides additional certificate information on the client and server to the environment, plus every CA certificate in the client certificate.
StrictRequire: Absolutely forces the connection to be forbidden when NSSRequireSSL or NSSRequire aren't met.
OptRenegotiate: Allows the SSL connection to be renegotiated using a different configuration. This is designed for a per-directory and is relatively expensive to do. For example, it can be used to force very strong ciphers in particular directories.

All options are disabled by default.

Example:

NSSOptions +FakeBasicAuth
<Files ~ "\.(cgi|shtml)$">
NSSOptions +StdEnvVars
<Files>

NSSRequireSSL

The request is forbidden unless the connection is using SSL. Only available in a per-directory context. This takes no arguments.

Example

NSSRequireSSL

NSSRequire

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.

Example

NSSRequire

NSSProxyEngine

Enables or disables mod_nss HTTPS support for mod_proxy.

Example

NSSProxyEngine on

NSSProxyProtocol

Specifies the SSL protocols that may be used in proxy connections. The syntax is identical to NSSProtocol.

Example

NSSProxyProtocol SSLv3

NSSProxyCipherSuite

Specifies the SSL ciphers available for proxy connections. The syntax is identical to NSSCipherSuite.

Example

NSSProxyCipherSuite
+rsa_3des_sha,-rsa_null_md5,-rsa_null_sha,+rsa_rc4_128_md5

NSSProxyNickname

The nickname of the client certificate to send if the remote server requests client authentication.

Example

NSSProxyNickname beta

NSSProxyCheckPeerCN

Compare the CN value of the peer certificate with the hostname being requested. If this is set to on, the default, then the request will fail if they do not match. If this is set to off then this comparison is not done. Note that this test is your only protection against a man-in-the-middle attack so leaving this as on is strongly recommended.

Example

NSSProxyCheckPeerCN on

Environment Variables

Quite a few environment variables (for CGI and SSI) may be set depending on the NSSOptions 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, TLSv1.0, TLSv1.1 or TLSv1.2
`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_V_REMAIN`	Number of days that the certificate is valid
`SSL_CLIENT_M_VERSION`	X.509 version of the client certificate
`SSL_CLIENT_M_SERIAL`	Serial number of the client certificate
`SSL_CLIENT_A_KEY`	Algorithm used for client key
`SSL_CLIENT_A_SIG`	Algorithm used for the signature of the client key
`SSL_CLIENT_S_DN`	Distinguished 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 certificate
`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).

Database Management

NSS stores it's certificates and keys in a set of files referred to as the "certificate database." The files by default (with NSS 3.x) are named cert8.db, key3.db and secmod.db. See the NSS documentation at http://www.mozilla.org/projects/security/pki/nss/ for more information on these specific files.

The NSS database also stores any Certificate Revocation Lists (CRLs).

Several NSS tools are available for managing certificates, keys, PKCS#11 modules and CRLs. These come with the NSS distribution. Here is a brief overview:

Tool	Description
`certutil`	Generate Certificate Signing Requests, install certificates and manage certificate trust flags.
`crlutil`	Manage certificate revocation lists (CRLs).
`modutil`	Manage the database of PKCS11 modules (`secmod.db`). Add modules and modify the properties of existing modules (such as whether a module is the default provider of some crypto service).
`pk12util`	Import and export keys and certificates in PKCS12 format.

Here are some quick, useful commands. This assumes that the NSPR and NSS libraries are in your LD_LIBRARY_PATH. Certificates may be referred to by either their DN or by a short nickname that is assigned when the certificate is added to the database. The nickname is the preferred method of referring to certificates. All of these commands use the -d option to specify the database location. The default is ~/.netscape and is probably not what you want.

Description	Command
Create a Database	certutil -N -d [path]
List all Certificates	certutil -L -d [path]
Extract a cert (Server-Cert) in ASCII	certutil -L -n Server-Cert -d [path] -a
Extract a cert and key (Server-Cert) in PKCS#12	pk12util -o server.p12 -n Server-Cert -d [path]
Import a cert and key (Import-Me) from PKCS#12	pk12util -i server.p12 -n Import-Me -d [path]

Importing OpenSSL Certificates

If you have existing OpenSSL certificates you can import them into an NSS certificate database.

To import a server certificate (nickname Server-Cert):

% openssl pkcs12 -export -in /path/to/certificate -inkey
/path/to/keyfile -out server.p12 -name "Server-Cert" -passout pass:foo

% pk12util -i server.p12 -d [path] -W foo

To import a CA certificate:

% certutil -A -n "myca" -t "CT,," -d [path] -a -i
/path/to/cacertificate

To import a CRL:

% openssl crl -in /path/to/crlfile -out /tmp/crl.tmp -inform PEM
-outform DER

% crlutil -I -t 1 -d [path] -i /tmp/crl.tmp

To verify that your server certificate was imported properly, you can have NSS validate it:

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

certutil: certificate is valid

Why is SSLv2 disabled?

All major browsers (Firefox, Internet Explorer, Mozilla, Netscape, Opera, and Safari) support SSL 3 and TLS so there is no need for a web server to support SSL 2. There are some known attacks against SSL 2 that are handled by SSL 3/TLS. SSL2 also doesn't support useful features like client authentication.

Frequently Asked Questions

Q. Does mod_nss support mod_proxy?

A. Yes but you need to make sure that mod_ssl is not loaded. mod_proxy provides a single interface for SSL providers and mod_nss defers to mod_ssl if it is loaded.

Sample Use Cases

I. Restart Apache using the NSS Internal Software Token

root


# certutil -L -d /etc/httpd/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

cacert                                                       CTu,Cu,Cu
Server-Cert                                                  u,u,u
alpha                                                        u,pu,u

NOTE: For actual deployments, the administrator should setup their own NSS security databases (e. g. - replace the default mod_nss NSS security databases located in /etc/httpd/alias), populate them with the appropriate certificates set with the proper trust attributes, and apply any changes necessary to the /etc/httpd/conf.d/nss.conf file such that mod_nss uses these NSS security databases.

certutil


# certutil -W -d /etc/httpd/alias

Enter Password or Pin for "NSS Certificate DB":

Enter a password which will be used to encrypt your keys.

The password should be at least 8 characters long,

and should contain at least one non-alphabetic character.



Enter new password:

Re-enter password:

Password changed successfully.

/etc/httpd/conf.d/nss.conf

NSSPassPhraseDialog builtin

NSSPassPhraseDialog file:/etc/httpd/password.conf

NOTE: Whenever httpd is invoked as a service/systemd process, the NSSPassPhraseDialog builtin parameter must be changed to point to a file URL in order to allow mod_nss to work with the Apache web server. This is because the mod_nss test for issuing the password prompt Please enter password for "internal" token: on the command line is only displayed when the command isatty(fileno(stdin)) is set to 'true', and when the command is entered from this type of invocation the value is 'false'. In order to see the prompt, one can set the NSSPassPhraseDialog builtin parameter and invoke httpd -D FOREGROUND from the command line.

NSSNickname

NSSNickname Server-Cert

NSSECCNickname

NSSECCNickname Server-Cert

NSSCertificateDatabase

NSSCertificateDatabase /etc/httpd/alias

/etc/httpd/password.conf

internal:<password>

/etc/httpd/password.conf

# chgrp apache /etc/httpd/password.conf

# chmod 640 /etc/httpd/password.conf


# ls -l /etc/httpd/password.conf

-rw-r-----. 1 root apache 18 Nov 27 14:05 /etc/httpd/password.conf


# service httpd restart

Redirecting to /bin/systemctl restart  httpd.service


# service httpd status
Redirecting to /bin/systemctl status  httpd.service
httpd.service - The Apache HTTP Server
   Loaded: loaded (/usr/lib/systemd/system/httpd.service; disabled)
   Active: active (running) since Wed 2013-11-27 15:25:48 PST; 1min 11s ago
  Process: 20804 ExecStop=/bin/kill -WINCH ${MAINPID} (code=exited, status=0/SUCCESS)
 Main PID: 20807 (httpd)
   Status: "Total requests: 0; Current requests/sec: 0; Current traffic:   0 B/sec"
   CGroup: name=systemd:/system/httpd.service
           |_____20807 /usr/sbin/httpd -DFOREGROUND
           |_____20808 /usr/libexec/nss_pcache 10027086 off /etc/httpd/alias
           |_____20809 /usr/sbin/httpd -DFOREGROUND
           |_____20810 /usr/sbin/httpd -DFOREGROUND
           |_____20811 /usr/sbin/httpd -DFOREGROUND
           |_____20812 /usr/sbin/httpd -DFOREGROUND
           |_____20813 /usr/sbin/httpd -DFOREGROUND

Nov 27 15:25:48 server.example.com systemd[1]: Started The Apache HTTP Server.

II. Restart Apache using the NSS FIPS Software Token

root


# certutil -L -d /etc/httpd/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

cacert                                                       CTu,Cu,Cu
Server-Cert                                                  u,u,u
alpha                                                        u,pu,u

certutil


# certutil -W -d /etc/httpd/alias

Enter Password or Pin for "NSS Certificate DB":

Enter a password which will be used to encrypt your keys.

The password should be at least 8 characters long,

and should contain at least one non-alphabetic character.



Enter new password:

Re-enter password:

Password changed successfully.

/etc/httpd/conf.d/nss.conf

NSSPassPhraseDialog builtin

NSSPassPhraseDialog file:/etc/httpd/password.conf

NOTE: Whenever httpd is invoked as a service/systemd process, the NSSPassPhraseDialog builtin parameter must be changed to point to a file URL in order to allow mod_nss to work with the Apache web server. This is because the mod_nss test for issuing the password prompt Please enter password for "NSS FIPS 140-2 Certificate DB" token: on the command line is only displayed when the command isatty(fileno(stdin)) is set to 'true', and when the command is entered from this type of invocation the value is 'false'. In order to see the prompt, one can set the NSSPassPhraseDialog builtin parameter and invoke httpd -D FOREGROUND from the command line.

NSSFIPS on

NSSEngine on

NSSNickname

NSSNickname Server-Cert

NSSECCNickname

NSSECCNickname Server-Cert

NSSCertificateDatabase

NSSCertificateDatabase /etc/httpd/alias

/etc/httpd/password.conf

NSS FIPS 140-2 Certificate DB:<password>

IMPORTANT: Notice that since the NSS FIPS software token is being used, the contents of the /etc/httpd/password.conf file references the password for the NSS FIPS software token (NSS FIPS 140-2 Certificate DB:<password>) rather than the NSS internal software token (internal:<password>).

/etc/httpd/password.conf

# chgrp apache /etc/httpd/password.conf

# chmod 640 /etc/httpd/password.conf


# ls -l /etc/httpd/password.conf

-rw-r-----. 1 root apache 39 Nov 27 15:48 /etc/httpd/password.conf


# service httpd restart

Redirecting to /bin/systemctl restart  httpd.service


# service httpd status
Redirecting to /bin/systemctl status  httpd.service
httpd.service - The Apache HTTP Server
   Loaded: loaded (/usr/lib/systemd/system/httpd.service; disabled)
   Active: active (running) since Wed 2013-11-27 16:26:07 PST; 4s ago
  Process: 21296 ExecStop=/bin/kill -WINCH ${MAINPID} (code=exited, status=0/SUCCESS)
 Main PID: 21299 (httpd)
   Status: "Total requests: 0; Current requests/sec: 0; Current traffic:   0 B/sec"
   CGroup: name=systemd:/system/httpd.service
           |_____21299 /usr/sbin/httpd -DFOREGROUND
           |_____21300 /usr/libexec/nss_pcache 10289231 on /etc/httpd/alias
           |_____21340 /usr/sbin/httpd -DFOREGROUND
           |_____21341 /usr/sbin/httpd -DFOREGROUND
           |_____21342 /usr/sbin/httpd -DFOREGROUND

Nov 27 16:26:07 server.example.com systemd[1]: Started The Apache HTTP Server.

mod_nss

Table of Contents

Introduction

Building

Installation

Certificate Generation

Server Startup

Migration

Configuration Directives

Environment Variables

Always Set

+StdEnvVars

+ExportCertData

Database Management

Importing OpenSSL Certificates

Why is SSLv2 disabled?

Frequently Asked Questions

Sample Use Cases

I. Restart Apache using the NSS Internal Software Token

II. Restart Apache using the NSS FIPS Software Token