You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSS 3.1 Loadable Root Certificates

Newsgroup: mozilla.dev.tech.crypto
Main technical contact: Bob Relyea
Manager: Wan-Teh Chang
Background
What Has Changed?
How Does This Affect My Code?
Where Can I Find the Plug-in Module?
Sample code for installing the module
Sample code to get the certs with the module loaded

Background

 Any PKI deployment must provide a scheme for propagating trust. Until now, the primary mechanism for doing so in PKI deployments with Netscape products has been to build root certificates for leading certificate authorities (CAs) into the products.

Unfortunately, an inherent problem with this approach has been the difficulty of upgrading CA certificates in the field. In addition, NSS is now open source. Vendors' products may have their own requirements for which trusted roots they include. Users may need to run several different products with different requirements at the same time.

Finally, some products, like servers, may need to ship without long lists of built-in trusted root certificates because these products often operate within their own heirarchy.

For these reasons, we would like to be able to change the built-in trusted root certificates on the fly without releasing a new product.

What Has Changed

NSS 3.1 no longer has a compiled-in list of root certificates. If you run NSS 3.1 in such a way as to generate a new database, these built-in root certificates do not get copied into the database. Instead, a PKCS #11 module is loaded after the database is initialized. The root certificates and trust information is loaded from this PKCS #11 module. Any trust bits in existing databases won't get overridden. Changes in trust get written back to the database, not the PKCS #11 module.

How Does This Affect My Code?

 First, you need to make sure this PKCS #11 module gets installed. You can do this one of two ways:
  • Make sure that the built-in module is installed in the same directory where the key and certificate databases live. NSS will find it and install it, looking under the following names:

    roots.dll   libroots.so   libroots.sl
    nssckbi.dll libnssckbi.so libnssckbi.sl
    mozckbi.dll libmozckbi.so libmozckbi.sl
    netckbi.dll libnetckbi.so libnetckbi.sl

    or

  • Use the SECMOD_AddNewModule() call in your application if the built-in module isn't loaded.
Next, you need to change any code that displays root certificates to search both the database and the PKCS #11 module.

Where Can I Find the Plug-in Module?

 The plug-in is built as part of NSS libraries under dist/${OBJDIR}/lib and is called one of the following: 
	 ttlibnssckbi.so
	 nssckbi.dll
	 libnssckbi.sl

Sample code for installing the module

 
	 /*
	 * initialize NSS as normal....
	 */


	/*
	 * check to see if you have a rootcert module installed
	 */

	hasroot = PR_FALSE;
	list = PK11_GetAllTokens(CK_INVALID_MECH,PR_FALSE,PR_FALSE, &pwdata);
	if (list) for (le->list->head; le; le->next) {
	   if (PK11_HasRootCerts(le->slot) {
		hasroot = PR_TRUE;
		break;
	   }
	}

	if (!hasroot) {
		dll_path = yourFindrootCertModuleInYourInstallTree();
		SECMOD_AddNewModule("Root Certs",dll_path, 0, 0);
	}

Sample code to get the certs with the module loaded

 Change 
	rv = CERT_TraversePermCerts(handle, <your_callback>, &numCerts);
to 
	list = PK11_GetAllTokens(CK_INVALID_MECH,PR_FALSE,PR_FALSE, &pwdata);
	if (list) for (le = list->head; le; le->next) {
	    rv = PK11_CertsInSlot(le->slot, <your_callback>, <your_params>);
	}