NSS Shared DB: Difference between revisions

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

These workarounds for the DBM engine's limitations are sufficiently onerous  

=== Where we are today ===

* cert8.db  - stores publicly accessible objects (certs, CRLs, S/MIME records).

In the presence of a multiaccess initialization string, during initialization

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

avoiding a repeat of this merge (making the merge idempotent).  This

string could be derived from the name of the application that used the

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

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,

token name string.

test for this.

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

*(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

things happen.  After this call succeeds the token name should be that

of the target token (see next step).

====== Failures and recovery ======

is not supplied. Application can choose to:  

# 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

:# possible input from the user.

:# the likelihood that the password will every be recovered.

password is not supplied. Application can choose to:

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

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

<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  

   Flow chart of NSS update actions for Mode 3:

When merging databases in, it's possible (even likely), that the shared  

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

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

it. This prompt must be clear we are asking for the master password for  

the running Mozilla app (Thunderbird, Firefox, Seamonkey, etc).

have a password we can proceed with the update without further prompting the

detect that and again proceed with the update without further prompting.

Mozilla apps can create more than one profile. Developers use this capability  

production environment.

couple of options.

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

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.

* cert_version current version is the current database version

* key_version is the current key database version

where:

* 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 ====

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

NSS will automatically load the legacy database support under the following conditions: