You are currently viewing a snapshot of 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, please file a bug.

Per-File Permissions

Mitch Stoltz

This page describes how to configure privileges for individual files.

What are Per-File Permissions?

Normally, permissions are granted to all pages from a particular host (or all pages signed by a particular certificate) as a bloc. When a script requests privileges, and no preference has been set by the user for that host or certificate, the "grant/deny" dialog is presented, and the user's decision applies to all files with that host/certificate.

A shortcoming of this model is that the local filesystem (everything accessed through the file:// protocol) is treated as a single security domain, such that privileges granted to one page on the local filesystem apply to all pages, which is potentially insecure. Per-File Permissions allow privileges to be granted to individual files.

How To Do It

Per-file permissions must be configured in the user preferences, either by a script with privileges to modify user preferences, or through some other means of editing the preferences file. As an example, suppose a Web application developer has installed an HTML page on the user's drive at C:/Programs/Webapp/index.html, and that page contains JavaScript which needs to access XPConnect. It would be insecure to grant the UniversalXPConnect privilege to every file on the user's drive. Instead of doing this, the developer could add these lines to the user's preferences:

user_pref("", "file:///C|/Programs/Webapp/index.html");
user_pref("capability.principal.myapp.granted", "UniversalXPConnect");

These lines will grant XPConnect access to index.html and no other file. The word myapp above can be replaced with any unique identifier for your application, as long as both lines have the same identifier. To state the syntax a little more generally:

user_pref("capability.principal.<group name>.id", "<Space-separated list of absolute URLs.>");
user_pref("capability.principal.<group name>.<granted|denied>", "<privilege name>");

where <group name> is any alphanumeric identifier and <privilege name> is UniversalXPConnect or any other privilege string representing the extended functionality your script needs. See the Signed Script Policy documentation for more information about privileges.


This mechanism is not cross-platform. Obviously, the URL in the example above would need to be changed for every platform, and also must be changed if the file is moved. A way to specify relative links would be better.