[ci skip] Update security guide

1 files changed, 93 insertions, 9 deletions

diff --git a/user_guide_src/source/general/security.rst b/user_guide_src/source/general/security.rst
index 3f93443bb..0c58f96b4 100644
--- a/user_guide_src/source/general/security.rst
+++ b/user_guide_src/source/general/security.rst
@@ -23,12 +23,12 @@ the following:
 -  Space
 
 Register_globals
-=================
+================
+
+During system initialization all global variables that are found to exist
+in the ``$_GET``, ``$_POST``, ``$_REQUEST`` and ``$_COOKIE`` are unset.
 
-During system initialization all global variables are unset, except
-those found in the ``$_GET``, ``$_POST``, and ``$_COOKIE`` arrays.
-The unsetting routine is effectively the same as
-*register_globals = off*.
+The unsetting routine is effectively the same as *register_globals = off*.
 
 display_errors
 ==============
@@ -60,12 +60,14 @@ from a form submission, COOKIE data, URI data, XML-RPC data, or even
 data from the SERVER array, you are encouraged to practice this three
 step approach:
 
-#. Filter the data as if it were tainted.
 #. Validate the data to ensure it conforms to the correct type, length,
    size, etc. (sometimes this step can replace step one)
-#. Escape the data before submitting it into your database.
+#. Filter the data as if it were tainted.
+#. Escape the data before submitting it into your database or outputting
+   it to a browser.
 
-CodeIgniter provides the following functions to assist in this process:
+CodeIgniter provides the following functions and tips to assist you
+in this process:
 
 XSS Filtering
 =============
@@ -76,13 +78,95 @@ your data, or other types of code that attempt to hijack cookies or
 do other malicious things. The XSS Filter is described
 :doc:`here <../libraries/security>`.
 
-Validate the data
+.. note:: XSS filtering should *only be performed on output*. Filtering
+	input data may modify the data in undesirable ways, including
+	stripping special characters from passwords, which reduces
+	security instead of improving it.
+
+CSRF protection
+===============
+
+CSRF stands for Cross-Site Request Forgery, which is the process of an
+attacker tricking their victim into unknowingly submitting a request.
+
+CodeIgniter provides CSRF protection out of the box, which will get
+automatically triggered for every non-GET HTTP request, but also needs
+you to create your submit forms in a certain way. This is explained in
+the :doc:`Security Library <../libraries/security>` documentation.
+
+Password handling
 =================
 
+It is *critical* that you handle passwords in your application properly.
+
+Unfortunately, many developers don't know how to do that, and the web is
+full of outdated or otherwise wrongful advices, which doesn't help.
+
+We would like to give you a list of combined do's and don'ts to help you
+with that. Please read below.
+
+-  DO NOT store passwords in plain-text format.
+
+   Always **hash** your passwords.
+
+-  DO NOT use Base64 or similar encoding for storing passwords.
+
+   This is as good as storing them in plain-text. Really. Do **hashing**,
+   not *encoding*.
+
+   Encoding, and encryption too, are two-way processes. Passwords are
+   secrets that must only be known to their owner, and thus must work
+   only in one direction. Hashing does that - there's *no* un-hashing or
+   de-hashing, but there is decoding and decryption.
+
+-  DO NOT use weak or broken hashing algorithms like MD5 or SHA1.
+
+   These algorithms are old, proven to be flawed, and not designed for
+   password hashing in the first place.
+
+   Also, DON'T invent your own algorithms.
+
+   Only use strong password hashing algorithms like BCrypt, which is used
+   in PHP's own `Password Hashing <http://php.net/password>`_ functions.
+
+   Please use them, even if you're not running PHP 5.5+, CodeIgniter
+   provides them for you as long as you're running at least PHP version
+   5.3.7 (and if you don't meet that requirement - please, upgrade).
+
+-  DO NOT ever display or send a password in plain-text format!
+
+   Even to the password's owner, if you need a "Forgotten password"
+   feature, just randomly generate a new, one-time (this is also important)
+   password and send that instead.
+
+-  DO NOT put artificial limits on your users' passwords.
+
+   There's no point in forcing a rule that a password can only be up to
+   a number of characters, or that it can't contain a certain set of
+   special characters.
+
+   Not only does this **reduce** security instead of improving it, but
+   there's literally no reason to do it. No technical limitations and
+   no (practical) storage constraints apply once you've hashed them, none!
+
+Validate input data
+===================
+
 CodeIgniter has a :doc:`Form Validation Library
 <../libraries/form_validation>` that assists you in
 validating, filtering, and prepping your data.
 
+Even if that doesn't work for your use case however, be sure to always
+validate and sanitize all input data. For example, if you expect a numeric
+string for an input variable, you can check for that with ``is_numeric()``
+or ``ctype_digit()``. Always try to narrow down your checks to a certain
+pattern.
+
+Have it in mind that this includes not only ``$_POST`` and ``$_GET``
+variables, but also cookies, the user-agent string and basically
+*all data that is not created directly by your own code*.
+
+
 Escape all data before database insertion
 =========================================