CrossSafe

CrossSafe provides secure cross domain JSON requests and partially implements the JSONRequest specification (the get and cancel methods). XMLHttpRequest follows a same origin policy, and because of this, when developing mashups that involve retrieving data from servers other than the origin, developers have typically had to decide between a secure, but slow connection that through a proxy, or a direct, faster, but unsecure dynamic script tag retrieval of information. CrossSafe allows fast, direct, and secure connections to foreign servers from the browser. CrossSafe uses the JSONRequest API as it provides a subset of the JSONRequest features. CrossSafe does not implement the entire specification. However, developers can use the JSONRequest API in CrossSafe to make cross domain requests (which is one of the primary motivations for JSONRequest), and if and when browsers implement JSONRequest natively, CrossSafe will simply leave the JSONRequest object alone, and code will continue to operate with the benefits of a native implementation. CrossSafe uses a technique for securing communication that is similiar to the Subspace approach which can be read about here.

CrossSafe does have limitations. CrossSafe still requires a callback parameter (like JSONP) to be implemented by foreign servers (it uses sandboxed script tag insertion internally). CrossSafe also requires certain host names on the origin server to be accessible. See the limitations sections for more information.

Setup

Unzip CrossSafe.zip into your web application.
Configure your web server and DNS entries to allow requests from webservice.mydomain.com, webservice1.mydomain.com,... webservicex.mydomain.com, where x is the maximum number of different domains you will access with CrossSafe.
Load CrossSafe in your web page:
You must ensure that the CrossSafe.directory value is set to the absolute path for the CrossSafe files.
Ensure that the cross domain JSON sources that you will be accessing support a callback parameter. If you are having trouble it may be helpful to set CrossSafe.visibleFrames to true to visually verify that the correct pages are being loaded.

In order for CrossSafe to work properly, it must be able to access it's files (mediator.html and untrusted.html) via http://webservicex.mydomain.com[CrossSafe.directory]mediator.html. The DNS, web server, and CrossSafe.directory value must be setup correctly such that this URL is accessible. Once this configured correctly, one can securely access JSON web services at different domains by simply using JSONRequest.get:

JSONRequest.get(url,done);

JSONRequest.get will request a JSON object from the given URL. The function returns an id value that identifies the current request. The done will be called when the request is completed. The done function will be called with three parameters:

function done(id,object,error)

The id identifies the request, the object is value that was returned, and the error object is included if any errors were encountered. For example:

JSONRequest.get("http://local.yahooapis.com/...?...&output=json",function(id,returnedObject) {
        ... Handle the response from the request
});

JSONRequest.cancel(id) can also be called to cancel a request. Please see the JSONRequest API for more information (note that the post method is not implemented in CrossSafe). The host name "webservice" can be configured to a different value. CrossSafe requires a three part host names (like www.mydomain.com) in order to work properly. By default, it will redirect to a host name with "www" prefix if a page with a two part domain name is loaded (like mydomain.com), to ensure proper security. This can also be configured.

Limitations

CrossSafe does not have all the capabilities of a native implementation of JSONRequest, nor is it even possible with only the capabilities of the current browsers. Current limitations include:

No JSONRequest.post - Currently CrossSafe does implement the post command. We plan to include this capability in a future release, but it will take a higher level of cooperation by servers than required by JSONP
Header Control - CrossSafe can not control the headers sent to servers, so there is no cookie stripping or header control as specified by the JSONRequest specification.
Origin Host Name - CrossSafe only works where the origin host is at least three levels deep, like name.domain.com.
cancel does not really end transfers - The cancel method follows the specification for correct JavaScript behavior (calling the callback function with cancellation, and not calling it later. However, it does not really cancel the underlying http transfer, as there is no way to do this with dynamic script tag insertion.
Cross Domain Disruption - The current version of CrossSafe does not provide complete protection between multiple cross domain sources. While the origin page is always secured from the cross domain requests, it is possible for them to interact with each other. This concern is mitigated by the fact that most uses of CrossSafe will be for accessing publicly available data (so no disclosure concern), and disruption concerns are usually less serious than could be achieved by creating an endless loop or endless alerts. A future upgrade should address the cross-domain issue.
No delay is added on repeated failures, since it is silly to try to limit developers with client side code when they have access to the source code.

Options

CrossSafe.directory Default: '/CrossSafe/' - This property defines the absolute directory (from the root of the webserver) where the CrossSafe files are located.
CrossSafe.allowUnsecure Default: false - This property defines whether CrossSafe can make unsecured cross domain connections when it is not properly configured to do sandboxing. This can useful in development when you are using a single name host name, and security does not matter. When code is deployed to a properly configured public web server, it will use secured connections.
CrossSafe.callbackParameter Default: 'callback' - This property defines the parameter to use to define the callback on cross domain requests. The JSONP protocol suggests using a callback parameter of 'jsonp', but 'callback' seems to be more widely used.
CrossSafe.redirectToHost Default: 'www' - This property defines the host name to prepend on the domain name when the site is accessed through such. CrossSafe can only properly sandbox with hosts with at least levels in it's hostname (like host.domain.com). If a site is accessed through domain.com, CrossSafe will redirect to www.domain.com (or whatever the property is set to). This property can be set to false if you do not want CrossSafe to ever redirect.
CrossSafe.strictlyObjects Default: true - This property specifies if only objects or arrays are allowed as valid JSON return values. If set to true, other JSON values are allowed such as strings, numbers, booleans, and null. The JSONRequest API specifies that only objects or arrays are allowed, so true is the default value.
CrossSafe.webServiceHostName Default: webservice - This property defines what host name prefix to use for the secured channels of communication. The CrossSafe files must be accessible through webservice.yourdomain.com.
CrossSafe.visibleFrames Default: false - This property defines whether the frames used for communication are visible, which can be helpful for debugging. Making them visible can be useful for debugging.