diff options
Diffstat (limited to 'user_guide_src/source/libraries')
| -rw-r--r-- | user_guide_src/source/libraries/encryption.rst | 39 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/form_validation.rst | 31 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/ftp.rst | 6 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/image_lib.rst | 2 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/output.rst | 26 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/security.rst | 24 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/table.rst | 36 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/zip.rst | 2 |
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 |