NSS Shared DB Howto

This document explains how to manually enable the shared DB feature in Mozilla applications. (Additional background information can be found on page NSS_Shared_DB).

It requires that all applications use NSS 3.12 (final) or later, which is shipped as part of Firefox 3.

It requires the use of NSS' certutil command line tool.

If you'd like to share data between Firefox 3 and Thunderbird 2, you must ensure that TB 2 does not use the old NSS library that came with it.

Ensuring a common NSS library is easy on operating systems that install NSS as a system package. Those (usually) ship the Firefox and Thunderbird applications without (an additional copy of) NSS.

On Linux/Unix/OSX based systems you should be able to simply replace old NSS libraries with newer ones.

On Microsoft Windows operating systems this might not work. For example, Thunderbird 2 and Firefox 3 link against different versions of the C runtime libraries and use different memory allocation libraries. Trying to use Thunderbird 2 with the NSS libraries that come as part of Firefox 3 is not advised and will likely result in random crashes.

Here are step by step instructions, assuming you are running on a Linux/Unix/OSX system with a bash-style shell, have ensured the common NSS library detail, and have obtained the certutil tool from version NSS 3.12.

Set environment variable NSS_DEFAULT_DB_TYPE to value "sql". You must ensure this environment variable is set when executing any of the thunderbird/firefox/certutil commands below.

You can do this by adding the following line to your ~/.bashrc file:

 export NSS_DEFAULT_DB_TYPE="sql" 

And the following line to your ~/.cshrc file:

 setenv NSS_DEFAULT_DB_TYPE "sql" 

• Logout and log back into your OS session
• Open a terminal

 cd ~/.thunderbird/yourprofile
 ls *.db

This directory should contain key3.db and cert8.db files, but no key4.db and no cert9.db files.

 mkdir backup-db
 cp *.db backup-db

The following series of commands will convert your existing database to a newer format.

• Start thunderbird
• Access security features, e.g. open cert manager. If you have a master password set, make sure you are prompted, it's required for the conversion.
• Wait while your certificate database gets converted (the UI might stall for a couple of moments)
• Quit thunderbird

 ls *.db

Now you should have files key4.db and cert9.db

 cd ~/.mozilla/firefox/yourprofile
 ls *.db

This directory should contain key3.db and cert8.db files, but no key4.db and no cert9.db files.

 mkdir backup-db
 cp *.db backup-db

The following series of commands will convert your existing database to a newer format.

• Start firefox
• Access security features, e.g. open cert manager. If you have a master password set, make sure you are prompted, it's required for the conversion.
• Wait while your certificate database gets converted (the UI might stall for a couple of moments)
• Quit firefox

 ls *.db

Now you should have files key4.db and cert9.db

Now let's create a shared location in a separate directory. We'll move the files from the Firefox profile over to the shared location. We'll create symbolic links in order to enable NSS to find the files.

 mkdir ~/.pki/nssdb
 mv -i key4.db cert9.db ~/.pki/nssdb
 ln -s ~/.pki/nssdb/key4.db .
 ln -s ~/.pki/nssdb/cert9.db .

Now we'll issue the certutil command that merges your Thunderbird certificate database into the shared database.

 cd ~/.thunderbird/yourprofile
 certutil --merge -d ~/.pki/nssdb --source-dir .

You must enter passwords as required. Wait until the merge completes.

 rm key4.db cert9.db
 ln -s ~/.pki/nssdb/key4.db .
 ln -s ~/.pki/nssdb/cert9.db .

That's it. Start Firefox and Thunderbird as you wish, enjoy the shared db feature. But remember, you must always have the environment variable set, or the applications will use your old non-merged db.

You may repeat the merge and symlink steps for additional profiles.

Please note that the shared database access is slower than the old one. It can be very slow when your files are stored on a remote file system, such as NFS. You should find a solution to have your files on your local system.

The above example uses a directory named ~/.pki/nssdb. Usually Mozilla applications use a random component for the directory name. Should a web application ever have an exploit that allows to access/read files with known names from a user's system, having the salt component is an additional security measure to makes exploiting harder. Therefore, instead of using the name nssdb, it would be reasonable to use a non-predictable directory name like ~/.pki/nssdb_random9384.