Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 7a9193afa6d890a91eb3528fa0e62df799b07ed6 / . / user_guide / libraries / encryption.html
blob: 5fa7b589e610f52698c998647bcdb5363a75cb0c [file] [log] [blame]
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Derek Allardafd99ac2008-01-19 19:59:14 +0000[diff] [blame]2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]3<head>
4
Derek Allard404e35d2007-08-07 01:00:45 +0000[diff] [blame]5<title>CodeIgniter User Guide : Encryption Class</title>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]6
7<style type='text/css' media='all'>@import url('../userguide.css');</style>
8<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
9
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]10<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]11<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]12<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +0000[diff] [blame]13<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]14
15<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
Derek Allard3d879d52008-01-18 19:41:32 +0000[diff] [blame]19<meta name='author' content='ExpressionEngine Dev Team' />
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]20<meta name='description' content='CodeIgniter User Guide' />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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.jpg" width="153" height="44" 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 Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.0</h1></td>
adminc0d5d522006-10-30 19:40:35 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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">
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame^]43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
admin10c3f412006-10-08 07:21:12 +0000[diff] [blame]45Encryption Class
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]46</td>
Derek Allardbc030912007-06-24 18:25:29 +0000[diff] [blame]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>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]48</tr>
49</table>
50<!-- END BREADCRUMB -->
51
52<br clear="all" />
53
54
55<!-- START CONTENT -->
56<div id="content">
57
58
admin10c3f412006-10-08 07:21:12 +0000[diff] [blame]59<h1>Encryption Class</h1>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]60
admin10c3f412006-10-08 07:21:12 +0000[diff] [blame]61<p>The Encryption Class provides two-way data encryption. It uses a scheme that pre-compiles
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]62the message using a randomly hashed bitwise XOR encoding scheme, which is then encrypted using
63the Mcrypt library. If Mcrypt is not available on your server the encoded message will
admine334c472006-10-21 19:44:22 +0000[diff] [blame]64still provide a reasonable degree of security for encrypted sessions or other such "light" purposes.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]65If Mcrypt is available, you'll effectively end up with a double-encrypted message string, which should
66provide a very high degree of security.</p>
67
68
69<h2>Setting your Key</h2>
70
admine334c472006-10-21 19:44:22 +0000[diff] [blame]71<p>A <em>key</em> is a piece of information that controls the cryptographic process and permits an encrypted string to be decoded.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]72In fact, the key you chose will provide the <strong>only</strong> means to decode data that was encrypted with that key,
admine7e1dcd2006-10-21 18:04:01 +0000[diff] [blame]73so not only must you chose the key carefully, you must never change it if you intend use it for persistent data.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]74
75<p>It goes without saying that you should guard your key carefully.
76Should someone gain access to your key, the data will be easily decoded. If your server is not totally under your control
77it's impossible to ensure key security so you may want to think carefully before using it for anything
78that requires high security, like storing credit card numbers.</p>
79
admine334c472006-10-21 19:44:22 +0000[diff] [blame]80<p>To take maximum advantage of the encryption algorithm, your key should be 32 characters in length (128 bits).
81The key should be as random a string as you can concoct, with numbers and uppercase and lowercase letters.
82Your key should <strong>not</strong> be a simple text string. In order to be cryptographically secure it
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]83needs to be as random as possible.</p>
84
admine334c472006-10-21 19:44:22 +0000[diff] [blame]85<p>Your key can be either stored in your <dfn>application/config/config.php</dfn>, or you can design your own
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]86storage mechanism and pass the key dynamically when encoding/decoding.</p>
87
88<p>To save your key to your <dfn>application/config/config.php</dfn>, open the file and set:</p>
89<code>$config['encryption_key'] = "YOUR KEY";</code>
90
91
92<h2>Message Length</h2>
93
admine334c472006-10-21 19:44:22 +0000[diff] [blame]94<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
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]95message. For example, if you encrypt the string "my super secret data", which is 21 characters in length, you'll end up
96with an encoded string that is roughly 55 characters (we say "roughly" because the encoded string length increments in
9764 bit clusters, so it's not exactly linear). Keep this information in mind when selecting your data storage mechanism. Cookies,
98for example, can only hold 4K of information.</p>
99
100
101<h2>Initializing the Class</h2>
102
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]103<p>Like most other classes in CodeIgniter, the Encryption class is initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]104
105<code>$this->load->library('encrypt');</code>
106<p>Once loaded, the Encrypt library object will be available using: <dfn>$this->encrypt</dfn></p>
107
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]108
109<h2>$this->encrypt->encode()</h2>
110
111<p>Performs the data encryption and returns it as a string. Example:</p>
112<code>
113$msg = 'My secret message';<br />
114<br />
115$encrypted_string = $this->encrypt->encode($msg);</code>
116
117<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>
118
119<code>
120$msg = 'My secret message';<br />
121$key = 'super-secret-key';<br />
122<br />
123$encrypted_string = $this->encrypt->encode($msg, $key);</code>
124
125
126<h2>$this->encrypt->decode()</h2>
127
128<p>Decrypts an encoded string. Example:</p>
129
130<code>
131$encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84';<br />
132<br />
133$plaintext_string = $this->encrypt->decode($encrypted_string);</code>
134
135
admin9fa00372006-10-12 18:20:13 +0000[diff] [blame]136<h2>$this->encrypt->set_cipher();</h2>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]137
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]138<p>Permits you to set an Mcrypt cipher. By default it uses <samp>MCRYPT_RIJNDAEL_256</samp>. Example:</p>
Derek Allard5a94ae52007-06-18 00:14:57 +0000[diff] [blame]139<code>$this->encrypt->set_cipher(MCRYPT_BLOWFISH);</code>
admin9fa00372006-10-12 18:20:13 +0000[diff] [blame]140<p>Please visit php.net for a list of <a href="http://php.net/mcrypt">available ciphers</a>.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]141
142<p>If you'd like to manually test whether your server supports Mcrypt you can use:</p>
143<code>echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup';</code>
144
145
146<h2>$this->encrypt->set_mode();</h2>
147
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]148<p>Permits you to set an Mcrypt mode. By default it uses <samp>MCRYPT_MODE_ECB</samp>. Example:</p>
Derek Allard5a94ae52007-06-18 00:14:57 +0000[diff] [blame]149<code>$this->encrypt->set_mode(MCRYPT_MODE_CFB);</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]150<p>Please visit php.net for a list of <a href="http://php.net/mcrypt">available modes</a>.</p>
151
152
153<h2>$this->encrypt->sha1();</h2>
154<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>
155<code>$hash = $this->encrypt->sha1('Some string');</code>
156
157<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
158function:</p>
159
160<code>$hash = sha1('Some string');</code>
161
162<p>If your server does not support SHA1 you can use the provided function.</p>
163
164
165
166</div>
167<!-- END CONTENT -->
168
169
170<div id="footer">
171<p>
172Previous Topic:&nbsp;&nbsp;<a href="email.html">Email Class</a>
173&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
174<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
175<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
176Next Topic:&nbsp;&nbsp;<a href="file_uploading.html">File Uploading Class</a>
Derek Allardc6441282007-07-04 23:54:32 +0000[diff] [blame]177</p>
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame^]178<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2007 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]179</div>
180
181</body>
182</html>