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.