Merge branch 'develop' into feature/session

8 files changed, 123 insertions, 43 deletions

diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst
index a4415f510..f29ebf4ed 100644
--- a/user_guide_src/source/libraries/encryption.rst
+++ b/user_guide_src/source/libraries/encryption.rst
@@ -5,13 +5,13 @@ Encryption Library
 The Encryption Library provides two-way data encryption. To do so in
 a cryptographically secure way, it utilizes PHP extensions that are
 unfortunately not always available on all systems.
-You must meet one of the following dependancies in order to use this
+You must meet one of the following dependencies in order to use this
 library:
 
 - `OpenSSL <http://php.net/openssl>`_ (and PHP 5.3.3)
 - `MCrypt <http://php.net/mcrypt>`_ (and `MCRYPT_DEV_URANDOM` availability)
 
-If neither of the above dependancies is met, we simply cannot offer
+If neither of the above dependencies is met, we simply cannot offer
 you a good enough implementation to meet the high standards required
 for proper cryptography.
 
@@ -84,14 +84,19 @@ your server is not totally under your control it's impossible to ensure
 key security so you may want to think carefully before using it for
 anything that requires high security, like storing credit card numbers.
 
-Your encryption key should be as long as the encyption algorithm in use
-allows. For AES-128, that's 128 bits or 16 bytes (charcters) long. The
-key should be as random as possible and it should **not** be a simple
-text string.
-
+Your encryption key **must** be as long as the encyption algorithm in use
+allows. For AES-128, that's 128 bits or 16 bytes (charcters) long.
 You will find a table below that shows the supported key lengths of
 different ciphers.
 
+The key should be as random as possible and it **must not** be a regular
+text string, nor the output of a hashing function, etc. In order to create
+a proper key, you must use the Encryption library's ``create_key()`` method
+::
+
+	// $key will be assigned a 16-byte (128-bit) random key
+	$key = $this->encryption->create_key(16);
+
 The key can be either stored in your *application/config/config.php*, or
 you can design your own storage mechanism and pass the key dynamically
 when encrypting/decrypting.
@@ -168,9 +173,9 @@ but regardless, here's a list of most of them:
 ============== ========= ============================== =========================================
 Cipher name    Driver    Key lengths (bits / bytes)     Supported modes
 ============== ========= ============================== =========================================
-AES-128        OpenSSL   128 / 16                       CBC, CTR, CFB, CFB8, OFB, ECB, GCM, XTS
-AES-192        OpenSSL   192 / 24                       CBC, CTR, CFB, CFB8, OFB, ECB, GCM, XTS
-AES-256        OpenSSL   256 / 32                       CBC, CTR, CFB, CFB8, OFB, ECB, GCM, XTS
+AES-128        OpenSSL   128 / 16                       CBC, CTR, CFB, CFB8, OFB, ECB, XTS
+AES-192        OpenSSL   192 / 24                       CBC, CTR, CFB, CFB8, OFB, ECB, XTS
+AES-256        OpenSSL   256 / 32                       CBC, CTR, CFB, CFB8, OFB, ECB, XTS
 Rijndael-128   MCrypt    128 / 16, 192 / 24, 256 / 32   CBC, CTR, CFB, CFB8, OFB, OFB8, ECB
 Rijndael-192   MCrypt    128 / 16, 192 / 24, 256 / 32   CBC, CTR, CFB, CFB8, OFB, OFB8, ECB
 Rijndael-256   MCrypt    128 / 16, 192 / 24, 256 / 32   CBC, CTR, CFB, CFB8, OFB, OFB8, ECB
@@ -234,7 +239,6 @@ CFB8        cfb8               MCrypt, OpenSSL   Same as CFB, but operates in 8-
 OFB         ofb                MCrypt, OpenSSL   N/A
 OFB8        ofb8               MCrypt            Same as OFB, but operates in 8-bit mode (not recommended).
 ECB         ecb                MCrypt, OpenSSL   Ignores IV (not recommended).
-GCM         gcm                OpenSSL           Provides authentication and therefore doesn't need a HMAC.
 XTS         xts                OpenSSL           Usually used for encrypting random access data such as RAM or hard-disk storage.
 Stream      stream             MCrypt, OpenSSL   This is not actually a mode, it just says that a stream cipher is being used. Required because of the general cipher+mode initialization process.
 =========== ================== ================= ===================================================================================================================================================
@@ -246,10 +250,9 @@ It's probably important for you to know that an encrypted string is usually
 longer than the original, plain-text string (depending on the cipher).
 
 This is influenced by the cipher algorithm itself, the IV prepended to the
-cipher-text and (unless you are using GCM mode) the HMAC authentication
-message that is also prepended. Furthermore, the encrypted message is also
-Base64-encoded so that it is safe for storage and transmission, regardless
-of a possible character set in use.
+cipher-text and the HMAC authentication message that is also prepended.
+Furthermore, the encrypted message is also Base64-encoded so that it is safe
+for storage and transmission, regardless of a possible character set in use.
 
 Keep this information in mind when selecting your data storage mechanism.
 Cookies, for example, can only hold 4K of information.
@@ -425,9 +428,6 @@ Option        Default value   Mandatory / Optional          Description
 cipher        N/A             Yes                           Encryption algorithm (see :ref:`ciphers-and-modes`).
 mode          N/A             Yes                           Encryption mode (see :ref:`encryption-modes`).
 key           N/A             Yes                           Encryption key.
-iv            N/A             No                            Initialization vector (IV).
-                                                            If not provided it will be automatically generated
-                                                            during encryption and looked for during decryption.
 hmac          TRUE            No                            Whether to use a HMAC.
                                                             Boolean. If set to FALSE, then *hmac_digest* and
                                                             *hmac_key* will be ignored.
@@ -444,9 +444,6 @@ raw_data      FALSE           No                            Whether the cipher-t
 	value is incorrect. This includes *hmac_key*, unless *hmac*
 	is set to FALSE.
 
-.. note:: If GCM mode is used, *hmac* will always be FALSE. This is
-	because GCM mode itself provides authentication.
-
 .. _digests:
 
 Supported HMAC authentication algorithms
diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst
index 2ae56d29a..aae9e3b89 100644
--- a/user_guide_src/source/libraries/form_validation.rst
+++ b/user_guide_src/source/libraries/form_validation.rst
@@ -505,11 +505,40 @@ function::
 			'required',
 			function($value)
 			{
-				// Check $value and return TRUE/FALSE
+				// Check $value
 			}
 		)
 	);
 
+Of course, since a Callable rule by itself is not a string, it isn't
+a rule name either. That is a problem when you want to set error messages
+for them. In order to get around that problem, you can put such rules as
+the second element of an array, with the first one being the rule name::
+
+	$this->form_validation->set_rules(
+		'username', 'Username',
+		array(
+			'required',
+			array('username_callable', array($this->users_model, 'valid_username'))
+		)
+	);
+
+Anonymous function (PHP 5.3+) version::
+
+	$this->form_validation->set_rules(
+		'username', 'Username',
+		array(
+			'required',
+			array(
+				'username_callable',
+				function($str)
+				{
+					// Check validity of $str and return TRUE or FALSE
+				}
+			)
+		)
+	);
+
 .. _setting-error-messages:
 
 Setting Error Messages
diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst
index dd9440443..4be1a6ea4 100644
--- a/user_guide_src/source/libraries/ftp.rst
+++ b/user_guide_src/source/libraries/ftp.rst
@@ -270,7 +270,7 @@ Class Reference
 		::
 
 			// Creates a folder named "bar"
-			$this->ftp->mkdir('/public_html/foo/bar/', DIR_WRITE_MODE);
+			$this->ftp->mkdir('/public_html/foo/bar/', 0755);
 
 	.. method:: chmod($path, $perm)
 
@@ -282,8 +282,8 @@ Class Reference
 		Permits you to set file permissions. Supply the path to the file or
 		directory you wish to alter permissions on::
 
-			// Chmod "bar" to 777
-			$this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE);
+			// Chmod "bar" to 755
+			$this->ftp->chmod('/public_html/foo/bar/', 0755);
 
 	.. method:: changedir($path[, $suppress_debug = FALSE])
 
diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst
index 16acf090b..a52cf3e02 100644
--- a/user_guide_src/source/libraries/image_lib.rst
+++ b/user_guide_src/source/libraries/image_lib.rst
@@ -137,6 +137,8 @@ Preference              Default Value           Options
                                                                                 image can be shown at a time, and it can't be positioned on the page. It
                                                                                 simply outputs the raw image dynamically to your browser, along with
                                                                                 image headers.
+**file_permissions**    0644                    (integer)                       File system permissions to apply on the resulting image file,               R, C, X, W
+                                                                                writing it to the disk. WARNING: Use octal integer notation!
 **quality**             90%                     1 - 100%                        Sets the quality of the image. The higher the quality the larger the        R, C, X, W
                                                                                 file size.
 **new_image**           None                    None                            Sets the destination image name/path. You'll use this preference when       R, C, X, W
diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst
index e49ea5366..218ec5896 100644
--- a/user_guide_src/source/libraries/output.rst
+++ b/user_guide_src/source/libraries/output.rst
@@ -205,4 +205,28 @@ Class Reference
 
 		Caches the current page for the specified amount of seconds.
 
-		For more information, please see the :doc:`caching documentation <../general/caching>`.
\ No newline at end of file
+		For more information, please see the :doc:`caching documentation <../general/caching>`.
+
+	.. method:: _display([$output = ''])
+
+		:param	string	$output: Output data override
+		:returns:	void
+		:rtype:	void
+
+		Sends finalized output data to the browser along with any server headers. It also stops benchmark
+		timers.
+
+		.. note:: This method is called automatically at the end of script execution, you won't need to 
+			call it manually unless you are aborting script execution using ``exit()`` or ``die()`` in your code.
+		
+		Example::
+			$response = array('status' => 'OK');
+
+			$this->output
+				->set_status_header(200)
+				->set_content_type('application/json', 'utf-8')
+				->set_output(json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES))
+				->_display();
+			exit;
+
+		.. note:: Calling this method manually without aborting script execution will result in duplicated output.
\ No newline at end of file
diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst
index fb875a0d9..0c51e342b 100644
--- a/user_guide_src/source/libraries/security.rst
+++ b/user_guide_src/source/libraries/security.rst
@@ -97,6 +97,13 @@ by editing the 'csrf_exclude_uris' config parameter::
 
 	$config['csrf_exclude_uris'] = array('api/person/add');
 
+Regular expressions are also supported (case-insensitive)::
+
+	$config['csrf_exclude_uris'] = array(
+		'api/record/[0-9]+',
+		'api/title/[a-z]+'
+	);
+
 ***************
 Class Reference
 ***************
@@ -156,4 +163,19 @@ Class Reference
 		This method acts a lot like PHP's own native ``html_entity_decode()`` function in ENT_COMPAT mode, only
 		it tries to detect HTML entities that don't end in a semicolon because some browsers allow that.
 
-		If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used.
\ No newline at end of file
+		If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used.
+
+	.. method:: get_random_bytes($length)
+
+		:param	int	$length: Output length
+		:returns:	A binary stream of random bytes or FALSE on failure
+		:rtype:	string
+
+		A convenience method for getting proper random bytes via ``mcrypt_create_iv()``,
+		``/dev/urandom`` or ``openssl_random_pseudo_bytes()`` (in that order), if one
+		of them is available.
+
+		Used for generating CSRF and XSS tokens.
+
+		.. note:: The output is NOT guaranteed to be cryptographically secure,
+			just the best attempt at that.
\ No newline at end of file
diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst
index 9d95eddfc..bb001e84c 100644
--- a/user_guide_src/source/libraries/table.rst
+++ b/user_guide_src/source/libraries/table.rst
@@ -95,24 +95,30 @@ The Table Class permits you to set a table template with which you can
 specify the design of your layout. Here is the template prototype::
 
 	$template = array(
-		'table_open'          => '<table border="0" cellpadding="4" cellspacing="0">',
+		'table_open'		=> '<table border="0" cellpadding="4" cellspacing="0">',
 
-		'heading_row_start'   => '<tr>',
-		'heading_row_end'     => '</tr>',
-		'heading_cell_start'  => '<th>',
-		'heading_cell_end'    => '</th>',
+		'thead_open'		=> '<thead>',
+		'thead_close'		=> '</thead>',
 
-		'row_start'           => '<tr>',
-		'row_end'             => '</tr>',
-		'cell_start'          => '<td>',
-		'cell_end'            => '</td>',
+		'heading_row_start'	=> '<tr>',
+		'heading_row_end'	=> '</tr>',
+		'heading_cell_start'	=> '<th>',
+		'heading_cell_end'	=> '</th>',
 
-		'row_alt_start'       => '<tr>',
-		'row_alt_end'         => '</tr>',
-		'cell_alt_start'      => '<td>',
-		'cell_alt_end'        => '</td>',
+		'tbody_open'		=> '<tbody>',
+		'tbody_close'		=> '</tbody>',
 
-		'table_close'         => '</table>'
+		'row_start'		=> '<tr>',
+		'row_end'		=> '</tr>',
+		'cell_start'		=> '<td>',
+		'cell_end'		=> '</td>',
+
+		'row_alt_start'		=> '<tr>',
+		'row_alt_end'		=> '</tr>',
+		'cell_alt_start'	=> '<td>',
+		'cell_alt_end'		=> '</td>',
+
+		'table_close'		=> '</table>'
 	);
 
 	$this->table->set_template($template);
@@ -288,4 +294,4 @@ Class Reference
 			$this->table->add_row('Mary', 'Monday', 'Air');
 			$this->table->add_row('John', 'Saturday', 'Overnight');
 
-			echo $this->table->generate();
\ No newline at end of file
+			echo $this->table->generate();
diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst
index 5ff7d07d6..4ca14086a 100644
--- a/user_guide_src/source/libraries/zip.rst
+++ b/user_guide_src/source/libraries/zip.rst
@@ -173,7 +173,7 @@ Class Reference
 		:rtype:	bool
 
 		Writes the Zip-encoded file to a directory on your server. Submit a valid server path ending in the file name.
-		Make sure the directory is writable (660 or 666 is usually OK). Example::
+		Make sure the directory is writable (755 is usually OK). Example::
 
 			$this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip