106
edits
Changes
m
More wordsmithing, use database and DBM consistently
*Synchronized updates, with application down time: The applications share the database read-only. If any update is desired, all the applications are shut down, and a database update program performs the update, then all the applications are restarted in read-only mode. Some server products, for example, have an administration program that stops the servers, updates the database that they share, and then restarts the servers. This results in undesirable downtime and desired database changes are delayed until the next interval in which such downtime is acceptable.
*Multiple copies with duplicated updates. Each application keeps its own copy of its databases, and applications communicate their changes to each other, so that each application may apply received changes to its own DBdatabase. FireFox and Thunderbird are examples of this. When one of those applications gets a new certificate and private key, the user may "export" that pair to a PKCS#12 file, and then import that file into the other application. Most users never master these steps, and so have databases entirely out of sync.
These workarounds for the DBM engine's limitations are sufficiently onerous
=== Where we are today ===
At initialization time, the application gives NSS a string that it uses as the pathname of a directory to store NSS's security and configuration data. NSS typically stores 3 dbm DBM files in that directory:
* cert8.db - stores publicly accessible objects (certs, CRLs, S/MIME records).
In the presence of a multiaccess initialization string, during initialization
NSS will try to find a shared library named librdb.so (rdb.dll on Windows) in its path and load it. This shared library is expected to implement a superset of the old dbm DBM interface. The main entry point is rdbopen, which will be passed the appName, database name, and open flags. The rdb shared library will pick a location or method to store the database (it may not necessarily be a file), then handle the raw db database records from NSS. The records passed to and from this library use exactly the same schema and record formats as the records in the DBM library.
=== The proposal ===
Mode 3A Applications are the most complicated. NSS provides some services to help applications get through and update and merge with the least interaction with the user of the application. Below is the steps a Mode 3A application should use whenever initializing NSS.
Step 0: Preparation: collect the directory and prefix names of both the source and target DBsdatabases. Prepare two strings for the operation:# <nowiki>A string to uniquely identify the source DBdatabase, for the purpose of
avoiding a repeat of this merge (making the merge idempotent). This
string could be derived from the name of the application that used the
source DBdatabase, from any application "instance" names (such as profilenames), from the absolute path name of the source DB database directory and theDB database prefixes, and from the last modification time of the source DBsdatabases.</nowiki><br><br><nowiki>
The algorithm for deriving this string should always produce the same
result for the same set of source files, so that the code can detect a
Note: The purpose of this string is to prevent multiple updates from the same old Database. This merge sequence is meant to be light enough weight that applications can safely call it each time they initialize.</nowiki><br>
# <nowiki>A string that will be the name of the removable PKCS#11 token that
will represent the source DBdatabase. This string must follow the rules for a
valid token name and must not contain any colon (:) characters.</nowiki>
Step 1: Call NSS_InitWithMerge, passing as arguments the destination
directory name, destination file name prefix, source directory name,
source file name prefix, unique source DB database identifier string, and source
token name string.
test for this.
* If the DB database slot token is not removable, then no update/merge is necessary, goto step 7.
* (optional) If PK11_NeedLogin() is not true then NSS has already completed the merge for you (no passwords were needed), skip to step 7.
* Otherwise it is necessary to authenticate to the source token, at step 3 below.
#*Otherwise, continue with step 4.
Step 4. Determine if it is necessary to authenticate to the target DBdatabase.This is done by calling PK11_IsLoggedIn for the DB database slot.*If the function indicates that the DB database token is NOT logged in, then it is necessary to authenticate to the target DBdatabase, with the step 5 below.
*(optional) Otherwise skip down to step 7.
Step 5. Call PK11_IsPresent(). You may think of this step as telling
you if the removable source token has been removed and the target token
has been inserted into the DB database slot. In reality, this call makes those
things happen. After this call succeeds the token name should be that
of the target token (see next step).
====== Failures and recovery ======
Exception A. Failure to authenticate to the source database <P>Application needs to decide what happens if the legacy password
is not supplied. Application can choose to:
# continue to use the legacy DB database and try to update later. (Probably a future restart of the application).
# reset the legacy database, throwing away any private or secret keys in the old database.
# shutdown NSS and initialize it only with the new shareable database.
: The exact strategy for recovering is application dependent and depends on factors like
:# the sensitivity of the application to loosing losing key data.
:# possible input from the user.
:# the likelihood that the password will every be recovered.
</P>Exception B. Failure to authenticate to the target database <P>Applications needs to decide what happens if the new shareable DBdatabase
password is not supplied. Application can choose to:
# continue to use the legacy DB database and try to update later.# force NSS to update those objects it can from the legacy DBdatabase,throwing away private keys and saved passwords, and trust information from the legacy DBdatabase.# force NSS to reset the shareable database password, throwing away private keys and saved passwords, and trust information from the shareable DBdatabase.</P>
Notes:
step 7; that is, during the call to NSS_InitWithMerge or during either
of the calls to PK11_Authenticate. This will depend on the ability of
the code to open the necessary DBsdatabases, the presence or absence of passwordson the DBsdatabases, and if both have passwords, it will depend on whether they
have the same password or different passwords, and when the
authentication attempts, if any, succeed. The system tries to complete the
2. If the attempt to open the
source DB database fails for any reason, the operation will behave as if thesource DB database was empty. It will record the unique source DB database identifierstring in the target DB database and act as if the merger is complete. This is similiar to what happens in all previous versions of NSS during database update. See "Database Merge" below for how to recover from this.
<pre>
/*
database. The application must be able to tell us where the old database lives,
since it's an application private directory compared the the multiple
application shared directory that the shared DB database lives in.
Flow chart of NSS update actions for Mode 3:
When merging databases in, it's possible (even likely), that the shared
database and legacy DB's databases have the same objects. In the case of certs and keys,
the merge is a simple matter of identifying duplicates and not updating them.
In the case of trust attributes, however, there are a number of choices:
# don't update duplicate trust (shared database copy wins).
# overwrite trust from the legacy DB database (legacy db database copy wins).
# calculate the least common denominator trust between them (take the least trusted values). (turning off trust wins).
# calculate the most common demonimnator trust between the two (turning on trust wins).
to do user interaction below.
If the legacy db database for the mozilla app has a master password set, we prompt for
it. This prompt must be clear we are asking for the master password for
the running Mozilla app (Thunderbird, Firefox, Seamonkey, etc).
Once we have a legacy db database password, or if we determine we don't need the legacydb database password (either because there isn't one, or because we are willing to loosethe data that was protected by it). We need to acquire the shareable dbdatabase's password so we can encrypt and MAC the data properly. If the shareable db database doesn't
have a password we can proceed with the update without further prompting the
user. If the shareable db database has the same password as the legacy dbdatabase, then we can
detect that and again proceed with the update without further prompting.
Mozilla apps can create more than one profile. Developers use this capability
to test bugs that new users are likely to run into without loosing losing their own
production environment.
couple of options.
# Allow profiles to be marked with 'private key/cert DB'sdatabases. This will change The Mozilla app from a Mode 3A app to a Mode 2A app. This will return developers to their previous semantic if they want, while allowing them to also test the interaction of different profiles and the same database. It would require UI changes to the profile manager, and it will require action on the part of the developer to get back to the old semantic.
# Treat only the default profile as Mode 3A and all other profiles as Mode 2A. This will allow profile separation to operate as is today with no changes. It does mean, however, that only default profiles will share keys with application.
# Provide the checkbox in option 1, but make it default as in option 2.
# Because merge does not require the complicated state machine to manage password acquisition, it can (and is) implemented outside the softoken itself.
Characteristic 3 allows database merge to work on arbitrary database types. You can merge a shareable db database into a shareable db database as well as an old database into a shareable db database (in fact, to a point, on arbitrary tokens - you can merge a hardware token into a shareable db database as long as the keys are extractable).
To merge 2 databases, the application simply opens the both databases and calls the new PK11_MergeTokens() call. PK11_MergeTokens() has the following signature:
* directory full path to where the database lives.
* certPrefix a prefix string to add in front of the key and cert db database names (if keyPrefix is null), null means add no prefix.* keyPrefix a prefix string to add in front of the key dbdatabase name. Null means use the same prefix as the cert dbdatabase name uses.
* cert_version current version is the current database version
* key_version is the current key database version
where:
* private is a pointer to opaque private data specific to the Shareable DB database implementation.
* sdb_type is the type of database (key [aka private] or cert [aka public]).
* sdb_flags specifies how the database was opened (ReadOnly, Create, etc).
==== legacy DB support ====
The old dbm DBM code can be supported with the above SDB structure with the following exceptions:
# The old db database code cannot be extensible (can't dynamically handle new types).
# A private interface may be needed to unwrap the private keys, or provide a handle to the password so the keys can be presented in the attribute format.
* legacy_ReadSecmodDB, legacy_ReleaseSecmodDBData, legacy_DeleteSecmodDB, legacy_AddSecmodDB - These functions provide access to the old secmod databases.
* legacy_Shutdown - This is called when NSS is through with all database support (that is when softoken shuts down).
* legacy_SetCryptFunctions - This is used to set some callbacks that the legacy db database can call to decrypt and encrypt password protected records (pkcs8 formatted keys, etc.). This allows the legacy database to translate it's database records to the new format without getting direct access to the keys.
NSS will automatically load the legacy database support under the following conditions:
