Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / cfe49186f26cd7bb6410abd4f1069b49325dc0e9 / . / user_guide / libraries / encryption.html
blob: 5c64127cb29353847ab12601ecdf67353f78af9f [file] [log] [blame]
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3<head>
4
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<title>Encryption Class : CodeIgniter User Guide</title>
7
8<style type='text/css' media='all'>@import url('../userguide.css');</style>
9<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
10
11<script type="text/javascript" src="../nav/nav.js"></script>
12<script type="text/javascript" src="../nav/prototype.lite.js"></script>
13<script type="text/javascript" src="../nav/moo.fx.js"></script>
14<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
15
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
19<meta name='author' content='ExpressionEngine Dev Team' />
20<meta name='description' content='CodeIgniter User Guide' />
21
22</head>
23<body>
24
25<!-- START NAVIGATION -->
26<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
27<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
28<div id="masthead">
29<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
30<tr>
Derek Jonesb8c038a2011-08-20 08:57:14 -0500[diff] [blame]31<td><h1>CodeIgniter User Guide Version 2.0.3</h1></td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
33</tr>
34</table>
35</div>
36<!-- END NAVIGATION -->
37
38
39<!-- START BREADCRUMB -->
40<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
41<tr>
42<td id="breadcrumb">
43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45Encryption Class
46</td>
47<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
48</tr>
49</table>
50<!-- END BREADCRUMB -->
51
52<br clear="all" />
53
54
55<!-- START CONTENT -->
56<div id="content">
57
58
59<h1>Encryption Class</h1>
60
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]61<p>The Encryption Class provides two-way data encryption. It uses a scheme that either compiles
Derek Jones09c77932010-08-31 13:17:10 -0500[diff] [blame]62the message using a randomly hashed bitwise XOR encoding scheme, or is encrypted using
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]63the Mcrypt library. If Mcrypt is not available on your server the encoded message will
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]64still provide a reasonable degree of security for encrypted sessions or other such "light" purposes.
Derek Jones09c77932010-08-31 13:17:10 -0500[diff] [blame]65If Mcrypt is available, you'll be provided with a high degree of security appropriate for storage.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]66
67
68<h2>Setting your Key</h2>
69
70<p>A <em>key</em> is a piece of information that controls the cryptographic process and permits an encrypted string to be decoded.
71In fact, the key you chose will provide the <strong>only</strong> means to decode data that was encrypted with that key,
72so not only must you choose the key carefully, you must never change it if you intend use it for persistent data.</p>
73
74<p>It goes without saying that you should guard your key carefully.
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]75Should someone gain access to your key, the data will be easily decoded. If your server is not totally under your control
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]76it's impossible to ensure key security so you may want to think carefully before using it for anything
77that requires high security, like storing credit card numbers.</p>
78
79<p>To take maximum advantage of the encryption algorithm, your key should be 32 characters in length (128 bits).
80The key should be as random a string as you can concoct, with numbers and uppercase and lowercase letters.
81Your key should <strong>not</strong> be a simple text string. In order to be cryptographically secure it
82needs to be as random as possible.</p>
83
84<p>Your key can be either stored in your <dfn>application/config/config.php</dfn>, or you can design your own
85storage mechanism and pass the key dynamically when encoding/decoding.</p>
86
87<p>To save your key to your <dfn>application/config/config.php</dfn>, open the file and set:</p>
88<code>$config['encryption_key'] = "YOUR KEY";</code>
89
90
91<h2>Message Length</h2>
92
93<p>It's important for you to know that the encoded messages the encryption function generates will be approximately 2.6 times longer than the original
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]94message. For example, if you encrypt the string "my super secret data", which is 21 characters in length, you'll end up
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]95with an encoded string that is roughly 55 characters (we say "roughly" because the encoded string length increments in
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]9664 bit clusters, so it's not exactly linear). Keep this information in mind when selecting your data storage mechanism. Cookies,
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]97for example, can only hold 4K of information.</p>
98
99
100<h2>Initializing the Class</h2>
101
102<p>Like most other classes in CodeIgniter, the Encryption class is initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>
103
104<code>$this->load->library('encrypt');</code>
105<p>Once loaded, the Encrypt library object will be available using: <dfn>$this->encrypt</dfn></p>
106
107
108<h2>$this->encrypt->encode()</h2>
109
110<p>Performs the data encryption and returns it as a string. Example:</p>
111<code>
112$msg = 'My secret message';<br />
113<br />
114$encrypted_string = $this->encrypt->encode($msg);</code>
115
116<p>You can optionally pass your encryption key via the second parameter if you don't want to use the one in your config file:</p>
117
118<code>
119$msg = 'My secret message';<br />
120$key = 'super-secret-key';<br />
121<br />
122$encrypted_string = $this->encrypt->encode($msg, $key);</code>
123
124
125<h2>$this->encrypt->decode()</h2>
126
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]127<p>Decrypts an encoded string. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]128
129<code>
130$encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84';<br />
131<br />
132$plaintext_string = $this->encrypt->decode($encrypted_string);</code>
133
Derek Allard2aab7852009-09-18 05:27:19 +0000[diff] [blame]134<p>You can optionally pass your encryption key via the second parameter if you don't want to use the one in your config file:</p>
135
136<code>
137$msg = 'My secret message';<br />
138$key = 'super-secret-key';<br />
139<br />
140$encrypted_string = $this->encrypt->decode($msg, $key);</code>
141
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]142
143<h2>$this->encrypt->set_cipher();</h2>
144
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]145<p>Permits you to set an Mcrypt cipher. By default it uses <samp>MCRYPT_RIJNDAEL_256</samp>. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]146<code>$this->encrypt->set_cipher(MCRYPT_BLOWFISH);</code>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]147<p>Please visit php.net for a list of <a href="http://php.net/mcrypt">available ciphers</a>.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]148
149<p>If you'd like to manually test whether your server supports Mcrypt you can use:</p>
150<code>echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup';</code>
151
152
153<h2>$this->encrypt->set_mode();</h2>
154
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]155<p>Permits you to set an Mcrypt mode. By default it uses <samp>MCRYPT_MODE_CBC</samp>. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]156<code>$this->encrypt->set_mode(MCRYPT_MODE_CFB);</code>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]157<p>Please visit php.net for a list of <a href="http://php.net/mcrypt">available modes</a>.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]158
159
160<h2>$this->encrypt->sha1();</h2>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]161<p>SHA1 encoding function. Provide a string and it will return a 160 bit one way hash. Note: SHA1, just like MD5 is non-decodable. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]162<code>$hash = $this->encrypt->sha1('Some string');</code>
163
164<p>Many PHP installations have SHA1 support by default so if all you need is to encode a hash it's simpler to use the native
165function:</p>
166
167<code>$hash = sha1('Some string');</code>
168
169<p>If your server does not support SHA1 you can use the provided function.</p>
170
Derek Jones09c77932010-08-31 13:17:10 -0500[diff] [blame]171<h2 id="legacy">$this->encrypt->encode_from_legacy(<kbd>$orig_data</kbd>, <kbd>$legacy_mode</kbd> = MCRYPT_MODE_ECB, <kbd>$key</kbd> = '');</h2>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]172<p>Enables you to re-encode data that was originally encrypted with CodeIgniter 1.x to be compatible with the Encryption library in CodeIgniter 2.x. It is only
173 necessary to use this method if you have encrypted data stored permanently such as in a file or database and are on a server that supports Mcrypt. "Light" use encryption
174 such as encrypted session data or transitory encrypted flashdata require no intervention on your part. However, existing encrypted Sessions will be
Derek Jones09c77932010-08-31 13:17:10 -0500[diff] [blame]175 destroyed since data encrypted prior to 2.x will not be decoded.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]176
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]177<p class="important"><strong>Why only a method to re-encode the data instead of maintaining legacy methods for both encoding and decoding?</strong> The algorithms in
Derek Jones09c77932010-08-31 13:17:10 -0500[diff] [blame]178 the Encryption library have improved in CodeIgniter 2.x both for performance and security, and we do not wish to encourage continued use of the older methods.
179 You can of course extend the Encryption library if you wish and replace the new methods with the old and retain seamless compatibility with CodeIgniter 1.x
180 encrypted data, but this a decision that a developer should make cautiously and deliberately, if at all.</p>
181
182<code>$new_data = $this->encrypt->encode_from_legacy(<kbd>$old_encrypted_string</kbd>);</code>
183
184<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
185<tr>
186 <th>Parameter</th>
187 <th>Default</th>
188 <th>Description</th>
189</tr>
190<tr>
191 <td class="td"><strong>$orig_data</strong></td>
192 <td class="td">n/a</td>
193 <td class="td">The original encrypted data from CodeIgniter 1.x's Encryption library</td>
194</tr>
195<tr>
196 <td class="td"><strong>$legacy_mode</strong></td>
197 <td class="td">MCRYPT_MODE_ECB</td>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]198 <td class="td">The Mcrypt mode that was used to generate the original encrypted data. CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will
Derek Jones09c77932010-08-31 13:17:10 -0500[diff] [blame]199 assume that to be the case unless overridden by this parameter.</td>
200</tr>
201<tr>
202 <td class="td"><strong>$key</strong></td>
203 <td class="td">n/a</td>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]204 <td class="td">The encryption key. This it typically specified in your config file as outlined above.</td>
Derek Jones09c77932010-08-31 13:17:10 -0500[diff] [blame]205</tr>
206</table>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]207
208</div>
209<!-- END CONTENT -->
210
211
212<div id="footer">
213<p>
214Previous Topic:&nbsp;&nbsp;<a href="email.html">Email Class</a>
215&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
216<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
217<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
218Next Topic:&nbsp;&nbsp;<a href="file_uploading.html">File Uploading Class</a>
219</p>
Derek Jones898949f2011-01-28 07:42:16 -0600[diff] [blame]220<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]221</div>
222
223</body>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]224</html>