Changes/NSSDefaultFileFormatSql

NSS Default File Format SQL

Summary

Change the NSS library default to use the sqlite based data storage, when applications don't specify their preferred storage file format.

Owner

• Name: Kai Engert
• Email: kaie@redhat.com
• Release notes ticket: #117

Current status

• Targeted release: Fedora 28
• Last updated: 2018-03-27
• Tracker bug: #1474771

Detailed Description

Applications that use the NSS library often use a database for storage of keys, certificates and trust. NSS supports two different file formats, one called DBM (based on berkeley DB files) and another one called SQL (based on sqlite DB files).

Today's default file format used by NSS, used when applications omit the type parameter, is the older DBM file format, which forbids parallel access to the storage. The suggestion is to change the default file format to SQL, which allows parallel access to the storage.

Applications, or users using the NSS command line utilities, often provide the database storage location using a simple directory path parameter. Some might not be aware, or forget, that the parameter can be prefixed with a type modifier, either "dbm:" or "sql:".

As a result, when not providing this parameter, the file format used will be the fragile DBM file format. This is particuarly problematic, if a user attempts to modify the NSS storage using command line tools, while another process, such as a daemon, is running concurrently, which also accesses the same database in the DBM file format. This often results in corrupted database storage, which cannot be recovered.

By changing the default, all applications that currently use the DBM file format, will automatically be migrated to the SQL file format. NSS has the ability to discover if a storage location (a directory) contains the DBM file format. If configured to use the modern SQL format, NSS will automatically perform a one-time conversion from the DBM to the SQL format.

The same applies to the NSS command line utilities. If the NSS library default is changed to SQL, the NSS tools will also trigger the one-time conversion, or access the already converted files.

Benefit to Fedora

The benefit will be less data corruption, because the SQL file format explicitly allows parallel access to the storage files by multiple applications.

NSS has been supporting this new file format for many years, and several applications have already opted in to explicitly use the new file format, so it can be considered stable.

Scope

• Proposal owners:

A small downstream patch needs to be applied to the NSS library package, which changes the library default.

• Other developers:

It's up to developers of NSS applications, if they accept the new default and an automatic conversion, or if they prefer to continue to use the classic DBM storage format. Although not recommended, developers can easily do so, by adding a "dbm:" prefix to the storage parameter they provide to NSS at NSS library initialization time.

• Release engineering: https://pagure.io/releng/issue/6883

No help should be necessary. No mass rebuild necessary.

• • List of deliverables: all

• Policies and guidelines: N/A

• Trademark approval: N/A

Upgrade/compatibility impact

Data will be migrated automatically on first access with the new default, if the new access triggers a code path that results in writing data.

Note that migration might happen in multiple steps. An application access, which doesn't provide the password for the key database, might trigger a migration of the contents of the cert8.db file to the cert9.db file, and might create a half-migrated key4.db file. On a future database access with the database password being available (application authenticates to the NSS database), NSS will complete the migration of the key3.db contents to the key4.db file.

In some scenarios it might be preferable to trigger an explicit migration of all contents. For example, if a daemon usually runs with read-only access to a database, and selinux restricts the daemon from writing the NSS database files, an automatic migration attempt may fail to write the migrated database files.

The following command can be used to trigger an explicit migration:

certutil -d sql:/path/to/database -N -f /path/to/database/password/file -@ /path/to/database/password/file

Although the -N command is primarily intended for creating a new database, it can also be used for migration inside a database directory. If an NSS database is already present in the directory provided with the -d parameter, no new databases will be created. In other words, the -N command is safe to use on existing database directories, it will not erase.

To create the correct parameter for the -d option, concat "sql:" and your /path/to/database, don't use space characters between the prefix and the path.

The -f and -@ parameters can be used to avoid interactive prompts during the migration. If you prefer to, you may run the command without these parameters, and enter your database password interactively three times. (For databases that aren't protected by a password, you may press enter at each of the three prompts for old and new password.)

If you'd like to perform a migration that doesn't prompt interactively, prepare a text file that contains the database password. (If the database uses an empty password, the text file should contain one empty line, or in other words, a newline character). For both -f and -@ parameters, provide the path to the password file.

The migration will not remove the old database files key3.db, cert8.db and secmod.db. You may decide to keep them for backup purposes. If you are using a NSS library that has been changed to use the sql database format by default, or if the application explicity uses the sql: prefix for the NSS database parameter, then NSS will use the new files key4.db, cert9.db and pkcs11.txt, only.

(See also https://bugzilla.mozilla.org/show_bug.cgi?id=1415912 which contains discussion about the recommended migration approach.)

The migration will not preserve file ownership and file permission of the old dbm database files, when creating the new database files. If special ownership or permissions are required, the explicit migration should be followed by appropriate calls to chmod / chown commands.

How To Test

Each application or server softare that uses NSS should be tested for successful data migration. Ideally, an application/server configuration should be used, which already contains data from a previous Fedora version. It should be tested that after migration to the new Fedora version, the software continues to operate as expected. In particular, this means that the software still has access to the locally configure private keys, certificates, trust settings which the application/server has configured. (This only applies to applications that perform this kind of operation.)

User Experience

The result changes will be restricted to the file system level, and to applications that use the NSS library default.

Previously, the following filenames were used for NSS storage:

• cert8.db
• key3.db
• secmod.db

After the change, the following filenames will be used:

• cert9.db
• key4.db
• pkcs11.txt

Applications that migrate data from an older version will contain both sets of files in their storage. However, after the conversion, the old files will no longer be used, they can be considered a one-time backup.

Applications that are executed for the first time with the new library default already effective, will only get the new storage files.

Performance with Network Filesystems (NFS, Samba)

Users of network filesystems may experience a major slowdown with some applications, such as Firefox.

When storing a user's home or application directory on a network filesystem, it is recommended to set the environment variable NSS_SDB_USE_CACHE=yes prior to starting applications that use NSS.

The environment variable enables the use of a caching strategy in NSS, that works around the slowness of network filesystems. Because this caching strategy causes a performance decrease on fast filesystems, it isn't used by default, but requires users to explicitly enable it.

Dependencies

No dependencies.

Contingency Plan

• Contingency mechanism: (What to do? Who will do it?) Revert the shipped configuration, NSS maintainer.
• Contingency deadline: beta freeze
• Blocks release? No
• Blocks product? No

Documentation

There are couple of upstream documents, which have been produced a couple of years ago, which might provide background on this change of technology.

• https://wiki.mozilla.org/NSS_Shared_DB
• https://wiki.mozilla.org/NSS_Shared_DB_And_LINUX

(Those documents partially focused on an additional property, which could potentially get achieved by migrating to the new file format: Having a common database for each system user, shared by all applications one user uses. However, this potential consolidation is more complicated to achieve. I suggest to EXCLUDE the consolidation from this change. The reason is the unresolved issue of merging databases from two sources to a single destination, when the sources used different database protection passwords. Migration will fail, unless application provides a user interface to prompt for the second database password.)

Release Notes

Yes, we should provide detailed release notes.