From 4e92e78b70299854205294ee43f056bda619e4db Mon Sep 17 00:00:00 2001
From: "ctrlaltca@gmail.com" <>
Date: Mon, 26 Mar 2012 10:10:51 +0000
Subject: added some documentation for the changes introduced to fix #391

---
 .../protected/pages/Advanced/Security.page         | 12 ++++++++++-
 .../protected/pages/Fundamentals/Components.page   | 25 +++++++++++++++++++++-
 2 files changed, 35 insertions(+), 2 deletions(-)

(limited to 'demos/quickstart/protected')

diff --git a/demos/quickstart/protected/pages/Advanced/Security.page b/demos/quickstart/protected/pages/Advanced/Security.page
index c3d0b511..226d7e49 100644
--- a/demos/quickstart/protected/pages/Advanced/Security.page
+++ b/demos/quickstart/protected/pages/Advanced/Security.page
@@ -36,7 +36,17 @@ One of the most important measures to prevent XSS attacks is to check user input
 <p id="730570" class="block-content">
 PRADO incorporates the work of <a href="http://pixel-apes.com/safehtml/">SafeHTML</a> and provides developers with a useful component called <tt>TSafeHtml</tt>. By enclosing content within a <tt>TSafeHtml</tt> component tag, the enclosed content are ensured to be safe to end users. In addition, the commonly used <tt>TTextBox</tt> has a <tt>SafeText</tt> property which contains user input that are ensured to be safe if displayed directly to end users.
 </p>
-
+<p class="block-content">
+With the broad use of active controls and more generally of AJAX-enabled controls using Javascript to transfer data between the server and the client, it's common to see attackers target javascript itself as a vector to inject malicious code.
+</p>
+<p class="block-content">
+Imagine a validator that uses an ajax callback to check user input from a textbox and returns an error message including the user input, example: 'The email address is not valid: test@example.com'.
+In such a situation user input <b>must</b> be checked to avoid possible injection.
+</p>
+<p class="block-content">
+The classic xss check involves checking for html tags inside the message and encode them; but since the message gets sent back to the client inside a javascript block, it needs to be encoded again to avoid any possible javascript escaping.
+By default PRADO encodes all variables sent clientside inside a javascript block to avoid any user-generated input from injecting malicious javascript code.  
+</p>
 <h2 id="5604">Cookie Attack Prevention</h2>
 <p id="730571" class="block-content">
 Protecting cookies from being attacked is of extreme important, as session IDs are commonly stored in cookies. If one gets hold of a session ID, he essentially owns all relevant session information.
diff --git a/demos/quickstart/protected/pages/Fundamentals/Components.page b/demos/quickstart/protected/pages/Fundamentals/Components.page
index 5662b53b..2ce96607 100644
--- a/demos/quickstart/protected/pages/Fundamentals/Components.page
+++ b/demos/quickstart/protected/pages/Fundamentals/Components.page
@@ -49,10 +49,33 @@ This is equivalent to the following,
 $name = $component->getFont()->getName();
 $component-&gt;getFont()-&gt;setName( $name );
 </com:TTextHighlighter>
+</p>
 
-
+<h3>Js-friendly properties</h3>
+<p class="block-content">
+A JavaScript-friendly property is a property that can accept both simple strings and raw javascript.
+Prado automatically encodes all properties sent clientside inside javascript blocks to avoid security problems (like injections or cross site scripting).
+If a property is known to always contain only safe javascript code and its value needs to bypass this encoding, that property can be defined in a special way that will make Prado mark its value as "safe".
+Js-friendly properties are identified by their name starting with 'js' (case insensitive):
+<com:TTextHighlighter CssClass="source block-content">
+// getter, defines a readable property 'Text'
+function getJsText() { … }
+// setter, defines a writable property 'Text', with $value being the value to be set to the property
+function setJsText(TJavaScriptLiteral $value) { … }
+</com:TTextHighlighter>
+Js-friendly properties can be accessed using both their Js-less name and their Js-enabled name:
+<com:TTextHighlighter CssClass="source block-content">
+// set some simple text as property value 
+$component-&gt;Text = 'text';
+// set some javascript code as property value
+$component-&gt;JsText = 'raw javascript';
+</com:TTextHighlighter>
+In the first case, the property value will automatically gets encoded when sent clientside inside a javascript block.
+In the second case, the property will be 'marked' as being a safe javascript statement and will not be encoded when rendered inside a javascript block.
+This special handling makes use of the <tt>TJavaScriptLiteral</tt> class. 
 </p>
 
+
 <h2 id="703">Component Events</h2>
 <p id="110119" class="block-content">
 Component events are special properties that take method names as their values. Attaching (setting) a method to an event will hook up the method to the places at which the event is raised. Therefore, the behavior of a component can be modified in a way that may not be foreseen during the development of the component.
-- 
cgit v1.2.3