wiki:WikiStart
Last modified 16 months ago Last modified on 10/02/15 22:40:40

mod_nss

mod_nss is an SSL provider derived from the mod_ssl module for the Apache web server that uses the Network Security Services (NSS) libraries. We started with mod_ssl and replaced the OpenSSL calls with NSS calls.

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.

History of Releases

Why use NSS instead of OpenSSL?

Use what is best for your needs.

This module was created so the Apache web server can use the same security libraries as the former Netscape server products acquired by Red Hat, notably the Fedora Directory Server (now called 389).

NSS is also used in the Mozilla clients, such as Firefox and Thunderbird. We are co-maintainers of NSS, and it better fits our particular needs.

What features does mod_nss provide?

For the most part there is a 1-1 mapping between the capabilities of mod_nss and mod_ssl.

In short, it supports:

  • SSLv3
  • TLSv1.0 - 1.2
  • client certificate authentication
  • SNI
  • hardware accelerators
  • Certificate Revocation Lists (CRLs)
  • OCSP

SSLv2 is disabled.

Some mod_ssl directives have been removed because they don’t apply, and some new ones added. The directives dropped are:

  • SSLRandomSeed
  • SSLSessionCache
  • SSLMutex
  • SSLCertificateChainFile
  • SSLCARevocationPath
  • SSLCARevocationFile
  • SSLVerifyDepth
  • SSLCryptoDevice

The mod_nss directives are all prefixed with NSS. The new directives are:

  • NSSCertificateDatabase
  • NSSNickname
  • NSSSession3CacheTimeout
  • NSSEnforceValidCerts
  • NSSFIPS
  • NSSOCSP
  • NSSSNI

How compatible is mod_nss to mod_ssl?

Because mod_nss was derived from mod_ssl, and actually includes several unmodified source files, it is very compatible. OpenSSL exposes some features that NSS doesn’t, and vice versa, but for a consumer of the module they are nearly functionally identical.

It is very simple to convert an existing mod_ssl configuration for use with mod_nss, but that isn’t really our goal. mod_nss was created to satisfy our needs for NSS support within Apache, not displace mod_ssl.

Documentation

http://git.fedorahosted.org/git/?p=mod_nss.git;a=blob_plain;f=docs/mod_nss.html;hb=HEAD

Mailing List

For questions, patchs, etc, you can the mod_nss mailing list is at https://www.redhat.com/mailman/listinfo/mod_nss-list

Source Code

Can I use my existing mod_ssl/OpenSSL certificates with mod_nss?

Yes. NSS uses a certificate database rather than discrete files. It is possible to convert the OpenSSL certificate files (these generally have .pem as the extension) for use with mod_nss. This involves converting the cert and key into a transportable file based on the PKCS #12 standard, then using an NSS utility to load it into your NSS database.

Here’s how:

  • Convert the OpenSSL key and certificate into a PKCS#12 file
% openssl pkcs12 -export -in cert.pem -inkey key.pem -out server.p12 -name \"Server-Cert\" -passout pass:foo
  • Create an NSS database. You just need to specify the database directory, not a specific file. This will create the 3 files that make up your database: cert8.db, key3.db and secmod.db.
% certutil -N -d /path/to/database
  • Load the PKCS #12 file into your NSS database.
% pk12util pk12util -i server.p12 -d /path/to/database -W foo

This loads your server certificate and gives it a “nickname.” This nickname is a short name for the certificate. This makes it easier to reference in configuration files than the certificate subject. In this case, you would set your NSSNickname value to “Server-Cert”

You will also need to import the CA certificate that issued the server certificate. In this case you don’t need the key of the CA, just the public certificate. Assuming you have the ASCII representation of it (e.g. a PEM file) you can load it as follows:

% certutil -d /path/to/database -A -n "My Local CA" -t \"CT,,\" -a -i /path/to/ca.pem

certutil and pk12util are both NSS utilities.

Why is SSL 2 disabled by default?

It has been obsolete since SSL3 was introduced in 1996 but has been kept around because of export restrictions and the fact that many sites still use it. Netcraft reports that usage is down considerably so there is no big hue and cry for it on the server side.

On the client side both Mozilla and IE7 are calling for dropping support for the protocol. By not allowing it by default in mod_nss we are forcing those who want to use it to reconsider.

How do I use the NSS command-line Utilities

Documentation on the NSS tools is available at http://www.mozilla.org/projects/security/pki/nss/tools/

Here are some common usages and some basic rules of thumb:

  • The -d argument tells the tool which database to operate on. It defaults to \~/.mozilla which isn’t very useful. If your database is in the same directory you are in you can always use -d .
  • There is nothing magical about a certificate nickname. We often use “Server-Cert” but it can be basically any ascii string. Use something that will be meaningful to you. This is the string that is displayed when you list certificates.
  • The -t argument sets the trust of a certificate. It is expressed as 3 values in this order: SSL, email, object signing separated by commas.

The possible values for trust are:

p    Valid peer
P    Trusted peer (implies p)
c    Valid CA
T    Trusted CA to issue client certificates (implies c)
C    Trusted CA to issue server certificates (SSL only)
      (implies c)
u    Certificate can be used for authentication or signing
w    Send warning (use with other attributes to inclu

Create a new NSS database

% certutil -N -d /path/to/database/dir

List all the certificates in an NSS database

% certutil -L -d /path/to/database/dir

Add a CA certificate to an NSS database

% certutil -A -d /path/to/database/dir -n "nickname" -t "CT,," -i -a < CAcert.txt

Generate a new Certificate Signing Request (CSR)

% certutil -R -d /path/to/database/dir -s "certificate DN" -o output_file -g <keysize>

The keysize is the # of bits in the private key. It can be in the range of 512-8192 bits, with a default of 1024.

In a server certificate DN the common name should have the form of: CN=fully-qualified hostname

When a client gets the certificate it compares the hostname in the URL to the CN in the subject of the certificate and if they don’t match a warning is presented to the user.

Examples include:

  • CN=myhost.example.com,o=My Org,c=US
  • CN=myhost.example.com,dc=myorg,dc=com

Verify that a certificate is valid and trusted

% certutil -V -u V -d /path/to/database/dir -n "nickname"

Load a PKCS#11 Module

% modutil -add "My Module Name" -libfile /path/to/library.so -dbdir /path/to/database/dir

This creates a pointer in secmod.db which will make the slots and tokens available. Some common commands to use with this:

List all PKCS#11 modules

% modutil -list -dbdir /path/to/database/dir

List all certificates on all tokens

% certutil -L -d /path/to/database/dir -h all