Changes

One of the main benefits of consolidating on a single crypto library is doing so create allows consolidation of management of certificates. In order to reap this benefit, however, we not only need to use a common crypto library, but also agree on a common way to use the crypto resources (keys/certs/tokens). This document attempts to explain how applications using NSS as a system library should initialize NSS for maximum effect.

The short summary: Except as noted below, all applications should initialize NSS with the following call:

3. The third exception is applications that must have a separately managed environment. Typically these applications would have a mode (probably default) which would open NSS normally, but could be configured to use their own NSS environment. The options to use the system or private environment should not be hard coded in the application, but should be under user/administrator control. Applications of this class would include Server products or test modes of application products (like Firefox profiles). In this mode the application should initialize NSS with it's traditional Init call, passing in the appropriate private database.

#Open a database in the home directory of the user running. With the flags specified by the application (probably ~/.pki/nssdb).

How this happens will be explained later, but first we discuss where the requirements for the above come from.

Type 1: User Application. These are applications like browsers, mail clients, etc. that individual users run. The user expects to be able to access all of his/her certificates from any application. The user also expects that system wide configuration is automatically available, though overridable by the user.

Type 3: Libraries. Libraries are a special case. The library may run in any kind of application or services.

User applications should open NSS using a shared database stored in ~/.pki/nssdb in the user's home directory. If the application needs to store new certificates (like a web browser), then it should open this database read/write. User's local preferences would be stored in this database. Changes the application wants to make will occur in this database. Any user specified tokens would also be stored in this database.

In addition, the application should own the system database /etc/pki/nssdb. This database should be opened read only. The user will typically not have permission to modify this database. This database will provide system level defaults for tokens to load and root certs to trust. This gives us hooks form things like IPA to manage and distribute trusted root certs system wide.

Option 1: Services applications, again, should open both sets of databases. The difference is service applications may actually have read permission on the key database in /etc/pki/nssdb. This means it can use /etc/pki/nssdb to share key material with other system services. Each service could start as it's own user or several services could run as a single user and share keys that way.

Option 3: Either option 1 or option 2 except the 'user' database for the server isn't necessarily stored in ~/.pki/{server_user}, but is configurable for each server.

NSS uses a file to decide what PKCS #11 modules, including softoken, to load. In NSS 3.11 and before this file was secmod.db and was a Berkeley database file. In NSS 3.12 the file is a flat text file called pkcs11.txt. In both NSS 3.11 and NSS 3.12, it is possible to tell NSS to load a shared library which provides PKCS #11 modules to load, called a ModuleDB. This module DB implements a couple of APIs which returns a list of modules, Adds a new module, and Deletes an old module. With one small mod to the pk11wrap code which controls this loading, it will be possible for a system to interpose it's own moduleDB. This module will receive the same string that softoken receives which contains the application's NSS preferences (readonly database, optimization options, etc), and can act on this string. In the simplest case, this module simply opens the user database, user PKCS #11 modules, system database, and system PKCS #11 modules. In the future, this module could tie back to some sort of managed database and open things according to the appropriate policy, and make system wide decisions on what database to load based on the application's request, the application itself, and the system administrator's policy.

[[ Most secure applications had an existence before the crypto consolidation effort. If those applications already had ways to store keys and certs, then there needs to be a way to automatically or semi-automatically migrate the keys and certs from those applications to the central NSS database. To assist in this NSS provides some built in primitives. --- work in progress ]]