Fixes #4480 New Kohana 3.2 Guide page on Encryption #232

Merged
merged 1 commit into from Mar 22, 2012
Jump to file or symbol
Failed to load files and symbols.
+107 −1
Split
@@ -1 +1,107 @@
-Discuss using encryption, including setting the encryption key in config.
+# Encryption
+
+Kohana supports built-in encryption and decryption via the [Encrypt] class, which is a convenient wrapper for the [Mcrypt library](http://www.php.net/mcrypt).
+
+To use the class, first start by ensuring you have the Mcrypt extension loaded to your PHP config. See the [Mcrypt Installation page](http://www.php.net/manual/en/mcrypt.installation.php) on php.net. The Mcrypt extension requires [libmcrypt](http://sourceforge.net/projects/mcrypt/files/).
+
+Next, copy the default config/encryption.php from system/config folder to your application/config folder.
+
+The default Encryption config file that ships with Kohana 3.2.x looks like this:
+
+ <?php defined('SYSPATH') or die('No direct script access.');
+
+ return array(
+
+ 'default' => array(
+ /**
+ * The following options must be set:
+ *
+ * string key secret passphrase
+ * integer mode encryption mode, one of MCRYPT_MODE_*
+ * integer cipher encryption cipher, one of the Mcrpyt cipher constants
+ */
+ 'cipher' => MCRYPT_RIJNDAEL_128,
+ 'mode' => MCRYPT_MODE_NOFB,
+ ),
+
+ );
+
+
+A couple of notes about the config.
+First, you may have multiple first-level keys other than 'default' if you need to.
+In this respect, the config file is similar to having multiple databases defined in your config/database.php file.
+Second, notice there is no key provided. You need to add that.
+It is strongly recommended that you choose a high-strength random key using the [pwgen linux program](http://linux.die.net/man/1/pwgen)...
+
+ shell> pwgen 63 1
+ trwQwVXX96TIJoKxyBHB9AJkwAOHixuV1ENZmIWyanI0j1zNgSVvqywy044Agaj
+
+...or by going to [GRC.com/passwords.htm](https://www.grc.com/passwords.htm).
+
+## Complete Config Example
+
+Here's a sample encryption configuration with three types of encryption defined. **If you copy this example, please change your keys!**
+
+ <?php defined('SYSPATH') or die('No direct script access.');
+ // application/config/encrypt.php
+
+ return array(
+
+ 'default' => array(
+ 'key' => 'trwQwVXX96TIJoKxyBHB9AJkwAOHixuV1ENZmIWyanI0j1zNgSVvqywy044Agaj',
+ 'cipher' => MCRYPT_RIJNDAEL_128,
+ 'mode' => MCRYPT_MODE_NOFB,
+ ),
+ 'blowfish' => array(
+ 'key' => '7bZJJkmNrelj5NaKoY6h6rMSRSmeUlJuTeOd5HHka5XknyMX4uGSfeVolTz4IYy',
+ 'cipher' => MCRYPT_BLOWFISH,
+ 'mode' => MCRYPT_MODE_ECB,
+ ),
+ 'tripledes' => array(
+ 'key' => 'a9hcSLRvA3LkFc7EJgxXIKQuz1ec91J7P6WNq1IaxMZp4CTj5m31gZLARLxI1jD',
+ 'cipher' => MCRYPT_3DES,
+ 'mode' => MCRYPT_MODE_CBC,
+ ),
+ );
+
+You can view the available encryption ciphers and modes on your system by running...
+
+ shell> php -r "print_r(get_defined_constants());" | grep MCRYPT
+
+For more information on Mcrypt ciphers, visit [php.net/mcrypt.ciphers](http://us3.php.net/manual/en/mcrypt.ciphers.php).
+
+## Basic Usage
+
+### Create an instance
+
+To use the Encryption class, obtain an instance of the Encrypt class by calling it's *instance* method,
+optionally passing the desired configuration group. If you do not pass a config group to the instance method,
+the default group will be used.
+
+ $encrypt = Encrypt::instance('tripledes');
+
+### Encoding Data
+
+Next, encode some data using the *encode* method:
+
+ $encrypt = Encrypt::instance('tripledes');
+ $encrypted_data = $encrypt->encode('Data to Encode');
+ // $encrypted_data now contains pCD5Z6oVdb9hbLxxV+FgGrhwVzZuhQoH
+
+[!!] Raw encrypted strings usually won't print in a browser, and may not store properly in a VARCHAR or TEXT field. For this reason, Kohana's Encrypt class automatically calls base64_encode on encode, and base64_decode on decode, to prevent this problem.
+
+[!!] One word of caution. The length of the encoded data expands quite a bit, so be sure your database column is long enough to store the encrypted data. If even one character is truncated, the data will not be recoverable.
+
+### Decoding Data
+
+To decode some data, load it from the place you stored it (most likely your database) then pass it to the *decode* method:
+
+ $encrypt = Encrypt::instance('tripledes');
+ $decoded_string = $encrypt->decode($encrypted_data);
+ echo $decoded_string;
+ // prints 'Data to Encode'
+
+You can't know in advance what the encoded string will be, and it's not reproducible, either.
+That is, you can encode the same value over and over, but you'll always obtain a different encoded version,
+even without changing your key, cipher and mode. This is because Kohana adds some random entropy before encoding it with your value.
+This ensures an attacker cannot easily discover your key and cipher, even given a collection of encoded values.