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);
};
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:
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.
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.
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).
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.
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:
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).
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.