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

Security project > Component Security > Using a Master Certificate

Using a Master Certificate for Remote Trust Grants

Mitch Stoltz

This page describes a feature available to distributors of Mozilla which allows establishing a "master certificate." This certificate can grant trust to other code-signing certificates without user interaction. These directions assume a basic familiarity with the concept of code signing. See the links in the provided documentation at the Component Security main page for more information.

The Need for this Feature

In general, if a script wishes to read a user's personal data or perform other sensitive operations, the user must give permission to the script, normally by answering Yes to a dialog box. For some Mozilla embedders and distributors, this dialog box detracts from the user experience, and another method of granting trust while still ensuring security must be used. By distributing a master certificate with the browser, a distributor can allow Web developers to perform sensitive operations in the browser without confirmation from the user.

Official mozilla.org software releases do not have a master certificate installed. The features described below will not work with releases from mozilla.org. These features can be activated at the discretion of individual Mozilla embedders/distributors.

The Master Certificate

The master certificate in Mozilla is defined as the signature on the systemSignature.jar file. On Windows and Unix systems, this file must be installed in the same directory as the Mozilla binary, and on Macintoshes, in the Essential Files directory. This file can be generated using SignTool, a Mozilla utility for signing code files. [Download Signtool] [Complete Documentation]

Assuming the certificate you want to use as a master certificate is installed in your certificate database, a master certificate file can be generated with a command like this:

signtool -k "MyMasterCertNickname" -Z systemSignature.jar emptyDir

... where myMasterCertNickname is the name of your master certificate as it is installed in your certificate database, and emptyDir is an empty directory, which indicates that no files besides the signature file itself should be placed in the jar. This command will create a file called systemSignature.jar which can be distributed with a Mozilla-based browser. Without this file present in the browser distribution, the master certificate features will not work.

Protect the private key to your master certificate very carefully. Remember that anyone who can sign scripts with your master certificate could gain unauthorized access to any browser distributed with that certificate.

The API

A script signed by the currently installed master certificate can call two functions which no other scripts can call. They are:

  • netscape.security.PrivilegeManager.setCanEnablePrivilege(certificateID, privilegeList)
    which can grant trust to other certificates, and
  • netscape.security.PrivilegeManager.invalidate(certificateID)
    which permanently revokes all trust from a certificate.

The first function, setCanEnablePrivilege, takes two arguments. The first is the certificate fingerprint, a cryptographic hash of the certificate to which you want to grant trust. The fingerprint is a hexadecimal number which uniquely identifies the certificate. For example, "85:2B:C1:7D:52:63:80:9E:62:02:47:4C:B2:17:BF:29." To find the fingerprint of a certificate in your database, open the Personal Security Manager (under the Tools menu in Mozilla), click the Certificates tab, select your certificate from the list, and click View.

The second argument to setCanEnablePrivilege is a space-separated list of the privileges you want the certificate to be able to use, for example UniversalPreferencesRead for access to browser preferences. The complete list of built-in privileges can be found in the Signed Script Policy documentation.

The Two-Certificate Model

It is important to understand that there are two certificates involved in this process. One is the master certificate which is installed by the distributor of a Mozilla-based browser, and the other is the certificate that will be used by the content creator to sign their own scripts, which I will call the website certificate. The process works like this:

  1. The ABC Company distributes a product based on Mozilla code which includes a systemSignature.jar file.
  2. Foobar.com, a Web content developer, obtains a digital certificate for code signing (the website certificate) and sends the certificate's fingerprint number to ABC.
  3. ABC writes a script which looks like this

    netscape.security.PrivilegeManager.setCanEnablePrivilege(
    "85:2B:C1:7D:52:63:80:9E:62:02:47:4C:B2:17:BF:29",
    "UniversalPreferencesRead UniversalBrowserRead")

    where the fingerprint number on the second line is replaced with the fingerprint of Foobar's site certificate. ABC signs this script with the master certificate and gives the signed script to Foobar.com. Note that the script above enables Foobar's certificate to use two privileges.
  4. Foobar.com creates a website and includes the signed script they received from ABC. When the site needs to access the user's browser privileges, Foobar signs its scripts with the certificate it obtained in step (1).
  5. When a user visits Foobar's site using ABC's browser, the "enabling" script that was signed by ABC runs first. After this script runs, any scripts signed by Foobar's website certificate can call

    netscape.security.PrivilegeManager.enablePrivilege("UniversalPreferencesRead")

    followed by (for example)

    var homepage = navigator.preference("browser.startup.homepage")

    which reads from the user's browser preferences. The user will not be presented with a confirmation dialog in this case. In fact, this script can be run without the user's knowledge.

The setCanEnablePrivilege script need only be run once on a user's browser. The privileges granted to Foobar's site certificate are stored in browser preferences and will be remembered for future visits to Foobar's site.

Why Two Certificates?

The two-certificate model allows the Mozilla distributor to decide which content creators can enable privileges silently, and to revoke trust from content creators if necessary. Using the companies from the example above, suppose Foobar.com's website certificate is compromised, or a security problem is found in their code. ABC, the Mozilla-based software distributor, can distribute a script signed with their master certificate which looks like this:

netscape.security.PrivilegeManager.invalidate(
"85:2B:C1:7D:52:63:80:9E:62:02:47:4C:B2:17:BF:29")

The invalidate function takes a single argument, the fingerprint of a certificate from which trust should be revoked. This script, when run, permanently revokes all trust from Foobar.com's website certificate, ensuring that scripts signed with this certificate can no longer perform dangerous actions. As with setCanEnablePrivilege, invalidate can only be called from a script signed with the master certificate. The invalidate function allows for a "flu shot" script to render harmless a compromised certificate or a dangerous signed script. If the master certificate, which is pre-installed in the browser, were used to sign website scripts, correcting a compromised certificate would require a browser upgrade.

Security project > Component Security > Using a Master Certificate