This is a snapshot of an early working draft and has therefore been superseded by the HTML standard.

This document will not be further updated.

HTML 5

Call For Comments — 27 October 2007

4.5. Browser state

The navigator attribute of the Window interface must return an instance of the ClientInformation interface, which represents the identity and state of the user agent (the client), and allows Web pages to register themselves as potential protocol and content handlers:

interface ClientInformation {
  readonly attribute boolean onLine;
  void registerProtocolHandler(in DOMString protocol, in DOMString uri, in DOMString title);
  void registerContentHandler(in DOMString mimeType, in DOMString uri, in DOMString title);
};

4.5.1. Custom protocol and content handlers

The registerProtocolHandler() method allows Web sites to register themselves as possible handlers for particular protocols. For example, an online fax service could register itself as a handler of the fax: protocol ([RFC2806]), so that if the user clicks on such a link, he is given the opportunity to use that Web site. Analogously, the registerContentHandler() method allows Web sites to register themselves as possible handlers for content in a particular MIME type. For example, the same online fax service could register itself as a handler for image/g3fax files ([RFC1494]), so that if the user has no native application capable of handling G3 Facsimile byte streams, his Web browser can instead suggest he use that site to view the image.

User agents may, within the constraints described in this section, do whatever they like when the methods are called. A UA could, for instance, prompt the user and offer the user the opportunity to add the site to a shortlist of handlers, or make the handlers his default, or cancel the request. UAs could provide such a UI through modal UI or through a non-modal transient notification interface. UAs could also simply silently collect the information, providing it only when relevant to the user.

There is an example of how these methods could be presented to the user below.

The arguments to the methods have the following meanings:

protocol (registerProtocolHandler() only)

A scheme, such as ftp or fax. The scheme must be treated case-insensitively by user agents for the purposes of comparing with the scheme part of URIs that they consider against the list of registered handlers.

The protocol value, if it contains a colon (as in "ftp:"), will never match anything, since schemes don't contain colons.

mimeType (registerContentHandler() only)

A MIME type, such as model/vrml or text/richtext. The MIME type must be treated case-insensitively by user agents for the purposes of comparing with MIME types of documents that they consider against the list of registered handlers.

User agents must compare the given values only to the MIME type/subtype parts of content types, not to the complete type including parameters. Thus, if mimeType values passed to this method include characters such as commas or whitespace, or include MIME parameters, then the handler being registered will never be used.

uri

The URI of the page that will handle the requests. When the user agent uses this URI, it must replace the first occurrence of the exact literal string "%s" with an escaped version of the URI of the content in question (as defined below), and then fetch the resulting URI using the GET method (or equivalent for non-HTTP URIs).

To get the escaped version of the URI, first, the domain part of the URI (if any) must be converted to its punycode representation, and then, every character in the URI that is not in the ranges given in the next paragraph must be replaced by its UTF-8 byte representation, each byte being represented by a U+0025 (%) character and two digits in the range U+0030 (0) to U+0039 (9) and U+0041 (A) to U+0046 (F) giving the hexadecimal representation of the byte.

The ranges of characters that must not be escaped are: U+002D (-), U+002E (.), U+0030 (0) to U+0039 (9), U+0041 (A) to U+005A (Z), U+005F (_), U+0061 (a) to U+007A (z), and U+007E (~).

If the user had visited a site that made the following call:

navigator.registerContentHandler('application/x-soup', 'http://example.com/soup?url=%s', 'SoupWeb™')

...and then clicked on a link such as:

<a href="http://www.example.net/chickenkïwi.soup">Download our Chicken Kiwi soup!</a>

...then, assuming this chickenkïwi.soup file was served with the MIME type application/x-soup, the UA might navigate to the following URI:

http://example.com/soup?url=http%3A%2F%2Fwww.example.net%2Fchickenk%C3%AFwi.soup

This site could then fetch the chickenkïwi.soup file and do whatever it is that it does with soup (synthesise it and ship it to the user, or whatever).

title

A descriptive title of the handler, which the UA might use to remind the user what the site in question is.

User agents should raise security exceptions if the methods are called with protocol or mimeType values that the UA deems to be "privileged". For example, a site attempting to register a handler for http URIs or text/html content in a Web browser would likely cause an exception to be raised.

User agents must raise a SYNTAX_ERR exception if the uri argument passed to one of these methods does not contain the exact literal string "%s".

User agents must not raise any other exceptions (other than binding-specific exceptions, such as for an incorrect number of arguments in an ECMAScript implementation).

This section does not define how the pages registered by these methods are used, beyond the requirements on how to process the uri value (see above). To some extent, the processing model for navigating across documents defines some cases where these methods are relevant, but in general UAs may use this information wherever they would otherwise consider handing content to native plugins or helper applications.

UAs must not use registered content handlers to handle content that was returned as part of a non-GET transaction (or rather, as part of any non-idempotent transaction), as the remote site would not be able to fetch the same data.

4.5.1.1. Security and privacy

These mechanisms can introduce a number of concerns, in particular privacy concerns.

Hijacking all Web usage. User agents should not allow protocols that are key to its normal operation, such as http or https, to be rerouted through third-party sites. This would allow a user's activities to be trivially tracked, and would allow user information, even in secure connections, to be collected.

Hijacking defaults. It is strongly recommended that user agents do not automatically change any defaults, as this could lead the user to send data to remote hosts that the user is not expecting. New handlers registering themselves should never automatically cause those sites to be used.

Registration spamming. User agents should consider the possibility that a site will attempt to register a large number of handlers, possibly from multiple domains (e.g. by redirecting through a series of pages each on a different domain, and each registering a handler for video/mpeg — analogous practices abusing other Web browser features have been used by pornography Web sites for many years). User agents should gracefully handle such hostile attempts, protecting the user.

Misleading titles. User agents should not rely wholy on the title argument to the methods when presenting the registered handlers to the user, since sites could easily lie. For example, a site hostile.example.net could claim that it was registering the "Cuddly Bear Happy Content Handler". User agents should therefore use the handler's domain in any UI along with any title.

Hostile handler metadata. User agents should protect against typical attacks against strings embedded in their interface, for example ensuring that markup or escape characters in such strings are not executed, that null bytes are properly handled, that over-long strings do not cause crashes or buffer overruns, and so forth.

Leaking Intranet URIs. The mechanism described in this section can result in secret Intranet URIs being leaked, in the following manner:

  1. The user registers a third-party content handler as the default handler for a content type.
  2. The user then browses his corporate Intranet site and accesses a document that uses that content type.
  3. The user agent contacts the third party and hands the third party the URI to the Intranet content.

No actual confidential file data is leaked in this manner, but the URIs themselves could contain confidential information. For example, the URI could be https://www.corp.example.com/upcoming-aquisitions/samples.egf, which might tell the third party that Example Corporation is intending to merge with Samples LLC. Implementors might wish to consider allowing administrators to disable this feature for certain subdomains, content types, or protocols.

Leaking secure URIs. User agents should not send HTTPS URIs to third-party sites registered as content handlers, in the same way that user agents do not send Referer headers from secure sites to third-party sites.

Leaking credentials. User agents must never send username or password information in the URIs that are escaped and included sent to the handler sites. User agents may even avoid attempting to pass to Web-based handlers the URIs of resources that are known to require authentication to access, as such sites would be unable to access the resources in question without prompting the user for credentials themselves (a practice that would require the user to know whether to trust the third-party handler, a decision many users are unable to make or even understand).

4.5.1.2. Sample user interface

This section is non-normative.

A simple implementation of this feature for a desktop Web browser might work as follows.

The registerProtocolHandler() method could display a modal dialog box:

||[ Protocol Handler Registration ]|||||||||||||||||||||||||||
|                                                            |
| This Web page:                                             |
|                                                            |
|    Kittens at work                                         |
|    http://kittens.example.org/                             |
|                                                            |
| ...would like permission to handle the protocol "x-meow:"  |
| using the following Web-based application:                 |
|                                                            |
|    Kittens-at-work displayer                               |
|    http://kittens.example.org/?show=%s                     |
|                                                            |
| Do you trust the administrators of the "kittens.example.   |
| org" domain?                                               |
|                                                            |
|              ( Trust kittens.example.org )  (( Cancel ))   |
|____________________________________________________________|

...where "Kittens at work" is the title of the page that invoked the method, "http://kittens.example.org/" is the URI of that page, "x-meow" is the string that was passed to the registerProtocolHandler() method as its first argument (protocol), "http://kittens.example.org/?show=%s" was the second argument (uri), and "Kittens-at-work displayer" was the third argument (title).

If the user clicks the Cancel button, then nothing further happens. If the user clicks the "Trust" button, then the handler is remembered.

When the user then attempts to fetch a URI that uses the "x-meow:" scheme, then it might display a dialog as follows:

||[ Unknown Protocol ]||||||||||||||||||||||||||||||||||||||||
|                                                            |
| You have attempted to access:                              |
|                                                            |
|    x-meow:S2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%3D               |
|                                                            |
| How would you like FerretBrowser to handle this resource?  |
|                                                            |
|  (o) Contact the FerretBrowser plugin registry to see if   |
|      there is an official way to handle this resource.     |
|                                                            |
|  ( ) Pass this URI to a local application:                 |
|      [ /no application selected/             ] ( Choose )  |
|                                                            |
|  ( ) Pass this URI to the "Kittens-at-work displayer"      |
|      application at "kittens.example.org".                 |
|                                                            |
|  [ ] Always do this for resources using the "x-meow"       |
|      protocol in future.                                   |
|                                                            |
|                                     ( Ok )  (( Cancel ))   |
|____________________________________________________________|

...where the third option is the one that was primed by the site registering itself earlier.

If the user does select that option, then the browser, in accordance with the requirements described in the previous two sections, will redirect the user to "http://kittens.example.org/?show=x-meow%3AS2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%253D".

The registerContentHandler() method would work equivalently, but for unknown MIME types instead of unknown protocols.