Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 56 insertions, 0 deletions

diff --git a/documentation/advanced/advanced-security.asciidoc b/documentation/advanced/advanced-security.asciidoc
new file mode 100644
index 0000000000..d3b0a5249c
--- /dev/null
+++ b/documentation/advanced/advanced-security.asciidoc
@@ -0,0 +1,56 @@
+---
+title: Common Security Issues
+order: 8
+layout: page
+---
+
+[[advanced.security]]
+= Common Security Issues
+
+[[advanced.security.sanitizing]]
+== Sanitizing User Input to Prevent Cross-Site Scripting
+
+You can put raw HTML content in many components, such as the [classname]#Label#
+and [classname]#CustomLayout#, as well as in tooltips and notifications. In such
+cases, you should make sure that if the content has any possibility to come from
+user input, you must make sure that the content is safe before displaying it.
+Otherwise, a malicious user can easily make a
+link:http://en.wikipedia.org/wiki/Cross-site_scripting[cross-site scripting
+attack] by injecting offensive JavaScript code in such components. See other
+sources for more information about cross-site scripting.
+
+Offensive code can easily be injected with [literal]#++<script>++# markup or in
+tag attributes as events, such as
+[parameter]#onLoad#.////
+TODO Consider an example, Alice, Bob,
+etc.
+////
+Cross-site scripting vulnerabilities are browser dependent, depending on the
+situations in which different browsers execute scripting markup.
+
+Therefore, if the content created by one user is shown to other users, the
+content must be sanitized. There is no generic way to sanitize user input, as
+different applications can allow different kinds of input. Pruning (X)HTML tags
+out is somewhat simple, but some applications may need to allow (X)HTML content.
+It is therefore the responsibility of the application to sanitize the input.
+
+Character encoding can make sanitization more difficult, as offensive tags can
+be encoded so that they are not recognized by a sanitizer. This can be done, for
+example, with HTML character entities and with variable-width encodings such as
+UTF-8 or various CJK encodings, by abusing multiple representations of a
+character. Most trivially, you could input [literal]#++<++# and [literal]#++>++#
+with [literal]#++&lt;++# and [literal]#++&gt;++#, respectively. The input could
+also be malformed and the sanitizer must be able to interpret it exactly as the
+browser would, and different browsers can interpret malformed HTML and
+variable-width character encodings differently.
+
+Notice that the problem applies also to user input from a
+[classname]#RichTextArea# is transmitted as HTML from the browser to server-side
+and is not sanitized. As the entire purpose of the [classname]#RichTextArea#
+component is to allow input of formatted text, you can not just remove all HTML
+tags. Also many attributes, such as [parameter]#style#, should pass through the
+sanitization.
+
+
+
+