439
edits
Changes
Linux NSS Initialization with shared databases
Use of NSS Shared Databases on Linux Platforms.
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.
Executive Summary.
The short summary: Except as noted below, all applications should initialize NSS with the following call:
rv = NSS_InitReadWrite(“sql:/etc/pki/nssdb”);
There are 3 classes of Exceptions.
1. The first exception is applications which must set special flags. The two most common flags are NSS_INIT_READONLY == 1 and NSS_INIT_OPTIMIZESPACE == 0. NOTE: applications that used to initialize READONLY because of the old dbm semantics no longer need to do so.
These applications should initialize with:
rv = NSS_Initialize(“sql:/etc/pki/nssdb”, “”, “”, “”, flags);
where flags are 0, NSS_INIT_READONLY, or NSS_INIT_READONLY|NSS_INIT_OPTIMIZESPACE. (Note: flags = NSS_INIT_OPTIMIZESPACE is the same as NSS_InitReadWrite() above. Also NSS_INIT_READONLY|NSS_INIT_OPTIMIZESPACE is the same as NSS_Init().).
2. The second exception is applications which want to perform automatic migration of an old NSS database from an old location to the new system location. These applications should initialize NSS with:
rv = NSS_InitMerge“sql:/etc/pki/nssdb”, “”, “”, “”, oldNSSdirectory, uniqueIDForOldDB, nameOfOldDBForPrompt, flags);
The application should then follow the automatic merge instructions in the shared database documentation.
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.
On linux, the effect of the above initialization will be to:
1)Open a database in the home directory of the user running. With the flags specified by the application (probably ~/.pki/nssdb).
2)Load any User specified PKCS #11 modules.
3)Open the system database in /etc/pki/nssdb readonly.
4)Load any System specified PKCS #11 modules.
5)Load the nss builtins module.
How this happens will be explained later.
First where the requirements for the above come from.
Requirements
Package Types.
There are 3 typical package times that may use NSS and it's databases:
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 2: System/Service Applications. These include things like web servers, mail servers, etc. These applications may want to share keys and certs with other servers, or they may want to have their own private copies of certs and keys.
Type 3: Libraries. Libraries are a special case. The library may run in any kind of application or services.
Type 1 packages: User applications.
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.
Type 2 packages: Services applications.
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 2: instead of sharing service level keys in /etc/pki/nssdb, we would specify a different database that services would open for shared key support (call it /etc/pki/services for now). In this case all three would be opened, but there would never be any keys in /etc/pki/nssdb, and User applications would not have access to /etc/pki/services.
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.
Type 3 packages:
Type 3 packages should open ~/pki/nssdb and /etc/pki/nssdb read only. If the packages are stand alone, this should be sufficient. If the packages are part of a bigger application, then it should follow the needs of that bigger application.
In short, all applications will need to open ~/pki/nssdb and /etc/pki/nssdb. Now, how can this most easily happen.
How NSS decides what to load.
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.
Certificate/Key Migration
[[ 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 ]]
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.
Executive Summary.
The short summary: Except as noted below, all applications should initialize NSS with the following call:
rv = NSS_InitReadWrite(“sql:/etc/pki/nssdb”);
There are 3 classes of Exceptions.
1. The first exception is applications which must set special flags. The two most common flags are NSS_INIT_READONLY == 1 and NSS_INIT_OPTIMIZESPACE == 0. NOTE: applications that used to initialize READONLY because of the old dbm semantics no longer need to do so.
These applications should initialize with:
rv = NSS_Initialize(“sql:/etc/pki/nssdb”, “”, “”, “”, flags);
where flags are 0, NSS_INIT_READONLY, or NSS_INIT_READONLY|NSS_INIT_OPTIMIZESPACE. (Note: flags = NSS_INIT_OPTIMIZESPACE is the same as NSS_InitReadWrite() above. Also NSS_INIT_READONLY|NSS_INIT_OPTIMIZESPACE is the same as NSS_Init().).
2. The second exception is applications which want to perform automatic migration of an old NSS database from an old location to the new system location. These applications should initialize NSS with:
rv = NSS_InitMerge“sql:/etc/pki/nssdb”, “”, “”, “”, oldNSSdirectory, uniqueIDForOldDB, nameOfOldDBForPrompt, flags);
The application should then follow the automatic merge instructions in the shared database documentation.
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.
On linux, the effect of the above initialization will be to:
1)Open a database in the home directory of the user running. With the flags specified by the application (probably ~/.pki/nssdb).
2)Load any User specified PKCS #11 modules.
3)Open the system database in /etc/pki/nssdb readonly.
4)Load any System specified PKCS #11 modules.
5)Load the nss builtins module.
How this happens will be explained later.
First where the requirements for the above come from.
Requirements
Package Types.
There are 3 typical package times that may use NSS and it's databases:
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 2: System/Service Applications. These include things like web servers, mail servers, etc. These applications may want to share keys and certs with other servers, or they may want to have their own private copies of certs and keys.
Type 3: Libraries. Libraries are a special case. The library may run in any kind of application or services.
Type 1 packages: User applications.
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.
Type 2 packages: Services applications.
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 2: instead of sharing service level keys in /etc/pki/nssdb, we would specify a different database that services would open for shared key support (call it /etc/pki/services for now). In this case all three would be opened, but there would never be any keys in /etc/pki/nssdb, and User applications would not have access to /etc/pki/services.
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.
Type 3 packages:
Type 3 packages should open ~/pki/nssdb and /etc/pki/nssdb read only. If the packages are stand alone, this should be sufficient. If the packages are part of a bigger application, then it should follow the needs of that bigger application.
In short, all applications will need to open ~/pki/nssdb and /etc/pki/nssdb. Now, how can this most easily happen.
How NSS decides what to load.
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.
Certificate/Key Migration
[[ 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 ]]
