Difference between revisions of "UnsafeWindow"

From GreaseSpot Wiki
Jump to navigationJump to search
(added addEventListener as an alternative to expandoing unsafeWindow)
 
(158 intermediate revisions by 25 users not shown)
Line 1: Line 1:
{{lowercase}}
{{DISPLAYTITLE:unsafeWindow}}
 
{{security}}
{{security}}


= Syntax =
== Description ==
 
'''unsafeWindow'''
 
= 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. unsafeWindow is shorthand for window.wrappedJSObject; it is the raw window object inside the XPCNativeWrapper provided by the Greasemonkey [[sandbox]].
 
unsafeWindow is insecure, and should be avoided when possible. User scripts absolutely should not use unsafeWindow if they are executed for arbitrary web pages, such as those with <code>@[[include]] *</code>.
 
= Examples =
 
unsafeWindow.document.title="Testing"
 
unsafeWindow.TestVarCreatedByDocument="Testing"
 
unsafeWindow.document.TestFunction("Test")
 
= Alternatives to unsafeWindow =
 
== Events ==
 
Event listeners never need to be created on unsafeWindow. Rather than using <code>unsafeWindow.onclick = function(event) { ... }</code>, use:
 
window.addEventListener('click', function(event) {
  ...
}, false);


[http://developer.mozilla.org/en/docs/DOM:element.addEventListener addEventListener at MDC]
This [object allows a [[User script]] to access "custom" properties set by the web page.
The user script is otherwise isolated from these properties.


== Functions defined in the page ==
:*'''USE OF UNSAFEWINDOW IS INSECURE, AND IT SHOULD BE AVOIDED WHENEVER POSSIBLE.'''


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:
unsafeWindow bypasses [[Greasemonkey]]'s security model, which exists to make sure that malicious web pages cannot alter objects in such a way as to make user scripts (which execute with more privileges than ordinary JavaScript running in a web page) do things that their authors or users did not intend.
User scripts should therefore avoid calling or in any other way depending on any properties on unsafeWindow - especially if they are executed for arbitrary web pages, such as those with <code>@[[Include and exclude rules|include]] *</code>..


location.href = 'javascript:void(pageFunc(123));';
== Examples ==


Larger blocks of code can also be executed this way:
<pre class='sample-bad'>
unsafeWindow.SomeVarInPage = "Testing";
</pre>


location.href = 'javascript:(' + encodeURI(uneval(function() {
<pre class='sample-bad'>
  // some code
unsafeWindow.SomeFunctionInPage("Test");
})) + ')();';
</pre>


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.
<pre class='sample-bad'>
var oldFunction = unsafeWindow.SomeFunctionInPage;
unsafeWindow.SomeFunctionInPage = function(text) {
  alert('Hijacked! Argument was ' + text + '.');
  return oldFunction(text);
};
</pre>


Another drawback is that this technique is rather ugly. Still, it is preferred over unsafeWindow.
== Alternatives to unsafeWindow ==


''Sometimes'', you just can't get around using unsafeWindow.
Most of the time, however, you can!
See [[:Category:Coding Tips:Interacting With The Page]] for details on various methods to interact with the page that do '''not''' use unsafeWindow.


[[Category:API Reference|U]]
[[Category:API_Reference|U]]
[[Category:Scripting context]]
[[Category:Security]]

Latest revision as of 15:17, 3 November 2017

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 [object allows a User script to access "custom" properties set by the web page. The user script is otherwise isolated from these properties.

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

unsafeWindow bypasses Greasemonkey's security model, which exists to make sure that malicious web pages cannot alter objects in such a way as to make user scripts (which execute with more privileges than ordinary JavaScript running in a web page) do things that their authors or users did not intend. User scripts should therefore avoid calling or in any other way depending on any properties on unsafeWindow - especially if they are executed for arbitrary web pages, such as those with @include *..

Examples

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

Alternatives to unsafeWindow

Sometimes, you just can't get around using unsafeWindow. Most of the time, however, you can! See Category:Coding Tips:Interacting With The Page for details on various methods to interact with the page that do not use unsafeWindow.