mod_nss

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 Mozilla. 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:

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. If you have a certificate with Subject Alternative Names then you can configure separate VirtualServer entries for eacon one. 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/key3.db
• /etc/httpd/nss/secmod.db

These 3 files make up an NSS certificate database.

If you have a sql: prefix on the path, like sql:/etc/httpd/nss, then it will generate an SQLite NSS database consisting of the following files:

• /etc/httpd/nss/cert9.db
• /etc/httpd/nss/key4.db
• /etc/httpd/nss/pkcs11.txt

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

• Exec a program which provides the token password (either by asking the user or other means. 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 course). 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

Details

• 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
  exec:/path/to/executable

The listed program will be executed. The only argument is the NSS token name to be authenticated. The return value of the program is ignored. Only what is printed on stdout is passed along as the password.

A trivial example script is:

  #!/bin/sh
  echo "secret123"
  

To prompt using systemd (as root):

  #!/bin/sh
  exec /bin/systemd-ask-password "Enter SSL pass phrase for $1: "
  

• Example

  NSSPassPhraseDialog builtin
  NSSPassPhraseDialog file:/etc/httpd/alias/password.conf
  NSSPassPhraseDialog exec:/usr/libexec/httpd/httpd-ssl-pass-dialog

• 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. To use a sqlite NSS database include the prefix sql: in the path.

Example

NSSCertificateDatabase /etc/httpd/conf/nss
  NSSCertificateDatabase sql:/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

Deprecated.

• NSSSession3CacheTimeout

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

• NSSSkipPermissionCheck

The NSS database will be checked to ensure that the user configured to run Apache as has owner or group read access to the database configured in NSSCertificateDatabase. This check can be disabled by setting NSSSkipPermissionCheck to on. The default is off

Example

NSSSkipPermissionCheck on

• 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 TLSv1.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 (with ecc-enabled set):

• rsa_3des_sha
• rsa_aes_128_sha
• rsa_aes_256_sha
• aes_128_sha_256
• aes_256_sha_256
• rsa_aes_128_gcm_sha_256
• fips_3des_sha
• ecdh_ecdsa_3des_sha
• ecdh_ecdsa_aes_128_sha
• ecdh_ecdsa_aes_256_sha
• ecdhe_ecdsa_3des_sha
• ecdhe_ecdsa_aes_128_sha
• ecdhe_ecdsa_aes_256_sha
• ecdh_rsa_3des_sha
• ecdh_rsa_aes_128_sha
• ecdh_rsa_aes_256_sha
• ecdhe_rsa_3des_sha
• ecdhe_rsa_aes_128_sha
• ecdhe_rsa_aes_256_sha
• ecdhe_ecdsa_aes_128_sha_256
• ecdhe_rsa_aes_128_sha_256
• ecdhe_ecdsa_aes_128_gcm_sha_256
• ecdhe_rsa_aes_128_gcm_sha_256

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

There are two options for configuring the available ciphers. mod_nss provides its own cipher list, a space-separated list of the SSL ciphers used, with the prefix + to enable or - to disable, using the Cipher Name value in the tables below.

Alternatively the mod_nss-style cipher definitions may be used, sslciphersuite.

The support options are:

• ALL
• COMPLEMENTOFALL
• DEFAULT
• RSA
• EDH
• NULL
• eNULL
• AES
• 3DES
• DES
• RC4,
• MD5
• SHA
• SHA1
• SHA256
• SSLv3
• TLSv1
• TLSv12
• HIGH
• MEDIUM
• LOW
• EXPORT
• EXPORT40
• EXPORT56

If a cipher string value contains a colon it is considered a mod_ssl-style cipher string.

If a cipher string value contains a comma it is considered a mod_nss-style cipher string.

If it contains neither then mod_nss first tries to apply OpenSSL ciphers then NSS ciphers.

All ciphers are disabled by default.

Available RSA ciphers are:

The available server-side DHE ciphers are:

Additionally there are a number of ECC ciphers:

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,-fips_des_sha, +fips_3des_sha,-rsa_aes_128_sha,-rsa_aes_256_sha
NSSCipherSuite ALL
NSSCipherSuite rsa_3des_sha
NSSCipherSuite RC4-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 (TLSv1.1 -> TLSv1.0 -> SSLv3.0), and does not allow exclusion of any protocols in the middle of a range (e. g. - TLSv1.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

• NSSSessionTickets

Enables or disables support for TLS Session tickets (RFC 5077). The default is off.

Example

NSSSessionTickets on

• 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] and SSL_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

• NSSRenegBufferSize

Configure the amount of memory that will be used for buffering the request body if a per-location SSL renegotiation is required due to changed access control requirements. The value is in bytes. The default is 128K. If set to 0 then no buffering is done.

Example

NSSRenegBufferSize 262144

• NSSSNI

Enables or disables Server Name Identification (SNI) extension check for TLS. This option is enabled by default. To disable SNI, set this to off in the default name-based VirtualHost.

Example

NSSSNI off

• NSSStrictSNIVHostCheck

Configures whether a non-SNI client is allowed to access a name-based VirtualHost. If set to on in the default name-based VirtualHost then clients that are SNI unaware cannot access any virtual host. If set to on in any other VirtualHost then SNI unaware clients cannot access this particular virtual host.

Example

NSSStrictSNIVHostCheck off

• 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

+StdEnvVars

+ExportCertData

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 for more information on these specific files. By default the NSS databases use the Berkeley Database format (cert8 and key3). To use the sqlite format (cert9 and key4) either include sql: in all references to the database (-d sql:/path/to/database) or export NSS_DEFAULT_DB_TYPE="sql".

For more details here

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:

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.

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