Difference between revisions of "UnsafeWindow"

From GreaseSpot Wiki
Jump to navigationJump to search
m (Reverting... what's up with the wiki source here... seems to be behind the times in wiki years)
(Symmetry update ONE MORE TO GO! Maybe sleep first)
Line 1: Line 1:
{{lowercase}}
{{lowercase}}
{{security}}
{{security}}
[[Category:API Reference]]
__NOTOC__
[[Category:Scripting context]]
[[Category:Security]]


= Syntax =
== Description ==


'''unsafeWindow'''
This [[API_reference|API]] object allows a [[User script]] to access "custom" properties--variable and functions defined in the page--set by the web page.


= Description =
[[User script]]s can use this object to access "custom" properties--variable and functions defined in the page--set by the web page.
This is done by bypassing [[Greasemonkey]]'s [[XPCNativeWrapper]]-based [[security]] model.
This is done by bypassing [[Greasemonkey]]'s [[XPCNativeWrapper]]-based [[security]] model.
The unsafeWindow object is shorthand for window.wrappedJSObject; it is the raw window object inside the XPCNativeWrapper provided by the Greasemonkey [[sandbox]].
The unsafeWindow object is shorthand for <code>window.wrappedJSObject;</code>. It is the raw window object inside the XPCNativeWrapper provided by the Greasemonkey [[sandbox]].


Use of unsafeWindow is insecure, and it should be avoided whenever possible.
:*'''USE OF UNSAFEWINDOW IS INSECURE, AND IT SHOULD BE AVOIDED WHENEVER POSSIBLE.'''
User scripts absolutely should not use unsafeWindow if they are executed for arbitrary web pages, such as those with <code>@[[Include and exclude rules|include]] *</code>.
User scripts absolutely should not use unsafeWindow if they are executed for arbitrary web pages, such as those with <code>@[[Include and exclude rules|include]] *</code>.
[[User script]] authors are '''strongly''' encouraged to learn how [[XPCNativeWrapper]]s work, and how to perform the desired function within their security context, instead of using unsafeWindow to break out.
[[User script]] authors are '''strongly''' encouraged to learn how [[XPCNativeWrapper]]s work, and how to perform the desired function within their security context, instead of using unsafeWindow to break out.
[[#Examples|Examples]] | [[#Alternatives_to_unsafeWindow|Alternatives to unsafeWindow]] | [[#Notes|Notes]]
== Syntax ==
'''unsafeWindow'''
:Value: Object
:Returns: Variant
:Compatibility: [[Version_history#0.5_beta|Greasemonkey 0.5b+]]
[[#Description|top]]


= Examples =
= Examples =
 
<code><pre>
  unsafeWindow.SomeVarInPage = "Testing";
  unsafeWindow.SomeVarInPage = "Testing";
</pre></code>


<code><pre>
  unsafeWindow.SomeFunctionInPage("Test");
  unsafeWindow.SomeFunctionInPage("Test");
</pre></code>


<code><pre>
  var oldFunction = unsafeWindow.SomeFunctionInPage;
  var oldFunction = unsafeWindow.SomeFunctionInPage;
  unsafeWindow.SomeFunctionInPage = function(text) {
  unsafeWindow.SomeFunctionInPage = function(text) {
   alert("Hijacked! Argument was " + text + ".");
   alert("Hijacked! Argument was " + text + ".");
   return oldFunction(text);
   return oldFunction(text);
  }
  };
</pre></code>


= Alternatives to unsafeWindow =
[[#Description|top]]


== Events ==
== Alternatives to unsafeWindow ==


Event listeners never need to be created on unsafeWindow. Rather than using <code>unsafeWindow.onclick = function(event) { ... }</code>, use:
[[#Events|Events]] | [[#Functions_defined_in_the_page|Functions defined in the page]]


window.addEventListener('click', function(event) {
=== Events ===
  ...
}, false);


[http://developer.mozilla.org/en/docs/DOM:element.addEventListener addEventListener at MDC]
:Event listeners never need to be created on unsafeWindow. Rather than using <code>unsafeWindow.onclick = function(event) { ... }</code>, use:


== Functions defined in the page ==
:<code><pre>window.addEventListener("click", function(event) { // some code }, false);</pre></code>


If a user script must execute a page function, it can use the '''[[location hack]]''' to call it safely. This involves setting location.href to a <code>javascript:</code> URL, which is like using a bookmarklet. For example:
:*[http://developer.mozilla.org/en/docs/DOM:element.addEventListener addEventListener at MDC]


location.href = 'javascript:void(pageFunc(123));';
[[#Description|top]] | [[#Alternatives_to_unsafeWindow|back]]


Larger blocks of code can also be executed this way:
=== Functions defined in the page ===


location.href = 'javascript:(' + encodeURI(uneval(function() {
:If a user script must execute a page function, it can use the '''[[location hack]]''' to call it safely. This involves setting location.href to a <code>javascript:</code> URL, which is like using a bookmarklet. For example:
  // some code
})) + ')();';


This code will run in the page context without leaking the [[sandbox]]. This code is completely separate from the rest of the script scope, sometimes limiting its usefulness. For example, data cannot be returned by the function.
:<code><pre>location.href = "javascript:void(pageFunc(123));";</pre></code>


Another drawback is that this technique is rather ugly. Still, it is preferred over unsafeWindow.
:Larger blocks of code can also be executed this way:
 
:<code><pre>location.href = "javascript:(" + encodeURI(uneval(function() { // some code })) + ")();";</pre></code>
 
:This code will run in the page context without leaking the [[sandbox]]. This code is completely separate from the rest of the script scope, sometimes limiting its usefulness. For example, data cannot be returned by the function.
 
:Another drawback is that this technique is rather ugly. Still, it is preferred over unsafeWindow.
 
[[#Description|top]] | [[#Alternatives_to_unsafeWindow|back]]
 
== Notes ==
[[#Description|top]]
 
[[Category:API_Reference|U]]
[[Category:Scripting context]]
[[Category:Security]]

Revision as of 00:25, 7 December 2007

Template:Lowercase

This command can open certain security holes in your user script, and it is recommended to use this command sparingly.

Please be sure to read the entire article and understand it before using it in a script.


Description

This API object allows a User script to access "custom" properties--variable and functions defined in the page--set by the web page.

This is done by bypassing Greasemonkey's XPCNativeWrapper-based security model. The unsafeWindow object is shorthand for window.wrappedJSObject;. It is the raw window object inside the XPCNativeWrapper provided by the Greasemonkey sandbox.

  • USE OF UNSAFEWINDOW IS INSECURE, AND IT SHOULD BE AVOIDED WHENEVER POSSIBLE.

User scripts absolutely should not use unsafeWindow if they are executed for arbitrary web pages, such as those with @include *. User script authors are strongly encouraged to learn how XPCNativeWrappers work, and how to perform the desired function within their security context, instead of using unsafeWindow to break out.

Examples | Alternatives to unsafeWindow | Notes

Syntax

unsafeWindow

Value: Object
Returns: Variant
Compatibility: Greasemonkey 0.5b+

top

Examples

 unsafeWindow.SomeVarInPage = "Testing";
 unsafeWindow.SomeFunctionInPage("Test");
 var oldFunction = unsafeWindow.SomeFunctionInPage;
 unsafeWindow.SomeFunctionInPage = function(text) {
   alert("Hijacked! Argument was " + text + ".");
   return oldFunction(text);
 };

top

Alternatives to unsafeWindow

Events | Functions defined in the page

Events

Event listeners never need to be created on unsafeWindow. Rather than using unsafeWindow.onclick = function(event) { ... }, use:
window.addEventListener("click", function(event) { // some code }, false);

top | back

Functions defined in the page

If a user script must execute a page function, it can use the location hack to call it safely. This involves setting location.href to a javascript: URL, which is like using a bookmarklet. For example:
location.href = "javascript:void(pageFunc(123));";
Larger blocks of code can also be executed this way:
location.href = "javascript:(" + encodeURI(uneval(function() { // some code })) + ")();";
This code will run in the page context without leaking the sandbox. This code is completely separate from the rest of the script scope, sometimes limiting its usefulness. For example, data cannot be returned by the function.
Another drawback is that this technique is rather ugly. Still, it is preferred over unsafeWindow.

top | back

Notes

top