1# Encryption 2 3Kohana supports built-in encryption and decryption via the [Encrypt] class, which is a convenient wrapper for the [Mcrypt library](http://www.php.net/mcrypt). 4 5To 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/). 6 7Next, copy the default config/encryption.php from system/config folder to your application/config folder. 8 9The default Encryption config file that ships with Kohana 3.2.x looks like this: 10 11 <?php defined('SYSPATH') OR die('No direct script access.'); 12 13 return array( 14 15 'default' => array( 16 /** 17 * The following options must be set: 18 * 19 * string key secret passphrase 20 * integer mode encryption mode, one of MCRYPT_MODE_* 21 * integer cipher encryption cipher, one of the Mcrpyt cipher constants 22 */ 23 'cipher' => MCRYPT_RIJNDAEL_128, 24 'mode' => MCRYPT_MODE_NOFB, 25 ), 26 27 ); 28 29 30A couple of notes about the config. 31First, you may have multiple first-level keys other than 'default' if you need to. 32In this respect, the config file is similar to having multiple databases defined in your config/database.php file. 33Second, notice there is no key provided. You need to add that. 34It is strongly recommended that you choose a high-strength random key using the [pwgen linux program](http://linux.die.net/man/1/pwgen)... 35 36 shell> pwgen 63 1 37 trwQwVXX96TIJoKxyBHB9AJkwAOHixuV1ENZmIWyanI0j1zNgSVvqywy044Agaj 38 39...or by going to [GRC.com/passwords.htm](https://www.grc.com/passwords.htm). 40 41## Complete Config Example 42 43Here's a sample encryption configuration with three types of encryption defined. **If you copy this example, please change your keys!** 44 45 <?php defined('SYSPATH') OR die('No direct script access.'); 46 // application/config/encrypt.php 47 48 return array( 49 50 'default' => array( 51 'key' => 'trwQwVXX96TIJoKxyBHB9AJkwAOHixuV1ENZmIWyanI0j1zNgSVvqywy044Agaj', 52 'cipher' => MCRYPT_RIJNDAEL_128, 53 'mode' => MCRYPT_MODE_NOFB, 54 ), 55 'blowfish' => array( 56 'key' => '7bZJJkmNrelj5NaKoY6h6rMSRSmeUlJuTeOd5HHka5XknyMX4uGSfeVolTz4IYy', 57 'cipher' => MCRYPT_BLOWFISH, 58 'mode' => MCRYPT_MODE_ECB, 59 ), 60 'tripledes' => array( 61 'key' => 'a9hcSLRvA3LkFc7EJgxXIKQuz1ec91J7P6WNq1IaxMZp4CTj5m31gZLARLxI1jD', 62 'cipher' => MCRYPT_3DES, 63 'mode' => MCRYPT_MODE_CBC, 64 ), 65 ); 66 67You can view the available encryption ciphers and modes on your system by running... 68 69 shell> php -r "print_r(get_defined_constants());" | grep MCRYPT 70 71For more information on Mcrypt ciphers, visit [php.net/mcrypt.ciphers](http://us3.php.net/manual/en/mcrypt.ciphers.php). 72 73## Basic Usage 74 75### Create an instance 76 77To use the Encryption class, obtain an instance of the Encrypt class by calling it's *instance* method, 78optionally passing the desired configuration group. If you do not pass a config group to the instance method, 79the default group will be used. 80 81 $encrypt = Encrypt::instance('tripledes'); 82 83### Encoding Data 84 85Next, encode some data using the *encode* method: 86 87 $encrypt = Encrypt::instance('tripledes'); 88 $encrypted_data = $encrypt->encode('Data to Encode'); 89 // $encrypted_data now contains pCD5Z6oVdb9hbLxxV+FgGrhwVzZuhQoH 90 91[!!] 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. 92 93[!!] 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. 94 95### Decoding Data 96 97To decode some data, load it from the place you stored it (most likely your database) then pass it to the *decode* method: 98 99 $encrypt = Encrypt::instance('tripledes'); 100 $decoded_string = $encrypt->decode($encrypted_data); 101 echo $decoded_string; 102 // prints 'Data to Encode' 103 104You can't know in advance what the encoded string will be, and it's not reproducible, either. 105That is, you can encode the same value over and over, but you'll always obtain a different encoded version, 106even without changing your key, cipher and mode. This is because Kohana adds some random entropy before encoding it with your value. 107This ensures an attacker cannot easily discover your key and cipher, even given a collection of encoded values.