user_guide/libraries/encryption.html - code-igniter-v3-giggi - Gitiles

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>

 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <title>Encryption Class : CodeIgniter User Guide</title>

 <style type='text/css' media='all'>@import url('../userguide.css');</style>
 <link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />

 <script type="text/javascript" src="../nav/nav.js"></script>
 <script type="text/javascript" src="../nav/prototype.lite.js"></script>
 <script type="text/javascript" src="../nav/moo.fx.js"></script>
 <script type="text/javascript" src="../nav/user_guide_menu.js"></script>

 <meta http-equiv='expires' content='-1' />
 <meta http-equiv= 'pragma' content='no-cache' />
 <meta name='robots' content='all' />
 <meta name='author' content='ExpressionEngine Dev Team' />
 <meta name='description' content='CodeIgniter User Guide' />

 </head>
 <body>

 <!-- START NAVIGATION -->
 <div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
 <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>
 <div id="masthead">
 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
 <tr>
 <td><h1>CodeIgniter User Guide Version 1.7.2</h1></td>
 <td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
 </tr>
 </table>
 </div>
 <!-- END NAVIGATION -->


 <!-- START BREADCRUMB -->
 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
 <tr>
 <td id="breadcrumb">
 <a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
 <a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
 Encryption Class
 </td>
 <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>
 </tr>
 </table>
 <!-- END BREADCRUMB -->

 <br clear="all" />


 <!-- START CONTENT -->
 <div id="content">


 <h1>Encryption Class</h1>

 <p>The Encryption Class provides two-way data encryption.  It uses a scheme that pre-compiles
 the message using a randomly hashed bitwise XOR encoding scheme, which is then encrypted using
 the Mcrypt library.  If Mcrypt is not available on your server the encoded message will
 still provide a reasonable degree of security for encrypted sessions or other such "light" purposes.
 If Mcrypt is available, you'll effectively end up with a double-encrypted message string, which should
 provide a very high degree of security.</p>


 <h2>Setting your Key</h2>

 <p>A <em>key</em> is a piece of information that controls the cryptographic process and permits an encrypted string to be decoded.
 In fact, the key you chose will provide the <strong>only</strong> means to decode data that was encrypted with that key,
 so not only must you choose the key carefully, you must never change it if you intend use it for persistent data.</p>

 <p>It goes without saying that you should guard your key carefully.
 Should someone gain access to your key, the data will be easily decoded.  If your server is not totally under your control
 it's impossible to ensure key security so you may want to think carefully before using it for anything
 that requires high security, like storing credit card numbers.</p>

 <p>To take maximum advantage of the encryption algorithm, your key should be 32 characters in length (128 bits).
 The key should be as random a string as you can concoct, with numbers and uppercase and lowercase letters.
 Your key should <strong>not</strong> be a simple text string. In order to be cryptographically secure it
 needs to be as random as possible.</p>

 <p>Your key can be either stored in your <dfn>application/config/config.php</dfn>, or you can design your own
 storage mechanism and pass the key dynamically when encoding/decoding.</p>

 <p>To save your key to your <dfn>application/config/config.php</dfn>, open the file and set:</p>
 <code>$config['encryption_key'] = "YOUR KEY";</code>


 <h2>Message Length</h2>

 <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
 message.  For example, if you encrypt the string "my super secret data", which is 21 characters in length, you'll end up
 with an encoded string that is roughly 55 characters (we say "roughly" because the encoded string length increments in
 64 bit clusters, so it's not exactly linear).  Keep this information in mind when selecting your data storage mechanism.  Cookies,
 for example, can only hold 4K of information.</p>


 <h2>Initializing the Class</h2>

 <p>Like most other classes in CodeIgniter, the Encryption class is initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>

 <code>$this->load->library('encrypt');</code>
 <p>Once loaded, the Encrypt library object will be available using: <dfn>$this->encrypt</dfn></p>


 <h2>$this->encrypt->encode()</h2>

 <p>Performs the data encryption and returns it as a string. Example:</p>
 <code>
 $msg = 'My secret message';<br />
 <br />
 $encrypted_string = $this->encrypt->encode($msg);</code>

 <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>

 <code>
 $msg = 'My secret message';<br />
 $key = 'super-secret-key';<br />
 <br />
 $encrypted_string = $this->encrypt->encode($msg, $key);</code>


 <h2>$this->encrypt->decode()</h2>

 <p>Decrypts an encoded string.  Example:</p>

 <code>
 $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84';<br />
 <br />
 $plaintext_string = $this->encrypt->decode($encrypted_string);</code>

 <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>

 <code>
 $msg = 'My secret message';<br />
 $key = 'super-secret-key';<br />
 <br />
 $encrypted_string = $this->encrypt->decode($msg, $key);</code>


 <h2>$this->encrypt->set_cipher();</h2>

 <p>Permits you to set an Mcrypt cipher.  By default it uses <samp>MCRYPT_RIJNDAEL_256</samp>.  Example:</p>
 <code>$this->encrypt->set_cipher(MCRYPT_BLOWFISH);</code>
 <p>Please visit php.net for a list of  <a href="http://php.net/mcrypt">available ciphers</a>.</p>

 <p>If you'd like to manually test whether your server supports Mcrypt you can use:</p>
 <code>echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup';</code>


 <h2>$this->encrypt->set_mode();</h2>

 <p>Permits you to set an Mcrypt mode.  By default it uses <samp>MCRYPT_MODE_ECB</samp>.  Example:</p>
 <code>$this->encrypt->set_mode(MCRYPT_MODE_CFB);</code>
 <p>Please visit php.net for a list of  <a href="http://php.net/mcrypt">available modes</a>.</p>


 <h2>$this->encrypt->sha1();</h2>
 <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>
 <code>$hash = $this->encrypt->sha1('Some string');</code>

 <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
 function:</p>

 <code>$hash = sha1('Some string');</code>

 <p>If your server does not support SHA1 you can use the provided function.</p>


 </div>
 <!-- END CONTENT -->


 <div id="footer">
 <p>
 Previous Topic:&nbsp;&nbsp;<a href="email.html">Email Class</a>
 &nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 <a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 <a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 Next Topic:&nbsp;&nbsp;<a href="file_uploading.html">File Uploading Class</a>
 </p>
 <p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006-2010 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
 </div>

 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>

	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<title>Encryption Class : CodeIgniter User Guide</title>

	<style type='text/css' media='all'>@import url('../userguide.css');</style>
	<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />

	<script type="text/javascript" src="../nav/nav.js"></script>
	<script type="text/javascript" src="../nav/prototype.lite.js"></script>
	<script type="text/javascript" src="../nav/moo.fx.js"></script>
	<script type="text/javascript" src="../nav/user_guide_menu.js"></script>

	<meta http-equiv='expires' content='-1' />
	<meta http-equiv= 'pragma' content='no-cache' />
	<meta name='robots' content='all' />
	<meta name='author' content='ExpressionEngine Dev Team' />
	<meta name='description' content='CodeIgniter User Guide' />

	</head>
	<body>

	<!-- START NAVIGATION -->
	<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
	<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>
	<div id="masthead">
	<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
	<tr>
	<td><h1>CodeIgniter User Guide Version 1.7.2</h1></td>
	<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
	</tr>
	</table>
	</div>
	<!-- END NAVIGATION -->


	<!-- START BREADCRUMB -->
	<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
	<tr>
	<td id="breadcrumb">
	<a href="http://codeigniter.com/">CodeIgniter Home</a>  ›
	<a href="../index.html">User Guide Home</a>  ›
	Encryption Class
	</td>
	<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  <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <input type="submit" class="submit" name="sa" value="Go" /></form></td>
	</tr>
	</table>
	<!-- END BREADCRUMB -->

	<br clear="all" />


	<!-- START CONTENT -->
	<div id="content">


	<h1>Encryption Class</h1>

	<p>The Encryption Class provides two-way data encryption. It uses a scheme that pre-compiles
	the message using a randomly hashed bitwise XOR encoding scheme, which is then encrypted using
	the Mcrypt library. If Mcrypt is not available on your server the encoded message will
	still provide a reasonable degree of security for encrypted sessions or other such "light" purposes.
	If Mcrypt is available, you'll effectively end up with a double-encrypted message string, which should
	provide a very high degree of security.</p>


	<h2>Setting your Key</h2>

	<p>A <em>key</em> is a piece of information that controls the cryptographic process and permits an encrypted string to be decoded.
	In fact, the key you chose will provide the <strong>only</strong> means to decode data that was encrypted with that key,
	so not only must you choose the key carefully, you must never change it if you intend use it for persistent data.</p>

	<p>It goes without saying that you should guard your key carefully.
	Should someone gain access to your key, the data will be easily decoded. If your server is not totally under your control
	it's impossible to ensure key security so you may want to think carefully before using it for anything
	that requires high security, like storing credit card numbers.</p>

	<p>To take maximum advantage of the encryption algorithm, your key should be 32 characters in length (128 bits).
	The key should be as random a string as you can concoct, with numbers and uppercase and lowercase letters.
	Your key should <strong>not</strong> be a simple text string. In order to be cryptographically secure it
	needs to be as random as possible.</p>

	<p>Your key can be either stored in your <dfn>application/config/config.php</dfn>, or you can design your own
	storage mechanism and pass the key dynamically when encoding/decoding.</p>

	<p>To save your key to your <dfn>application/config/config.php</dfn>, open the file and set:</p>
	<code>$config['encryption_key'] = "YOUR KEY";</code>


	<h2>Message Length</h2>

	<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
	message. For example, if you encrypt the string "my super secret data", which is 21 characters in length, you'll end up
	with an encoded string that is roughly 55 characters (we say "roughly" because the encoded string length increments in
	64 bit clusters, so it's not exactly linear). Keep this information in mind when selecting your data storage mechanism. Cookies,
	for example, can only hold 4K of information.</p>


	<h2>Initializing the Class</h2>

	<p>Like most other classes in CodeIgniter, the Encryption class is initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>

	<code>$this->load->library('encrypt');</code>
	<p>Once loaded, the Encrypt library object will be available using: <dfn>$this->encrypt</dfn></p>


	<h2>$this->encrypt->encode()</h2>

	<p>Performs the data encryption and returns it as a string. Example:</p>
	<code>
	$msg = 'My secret message';<br />
	<br />
	$encrypted_string = $this->encrypt->encode($msg);</code>

	<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>

	<code>
	$msg = 'My secret message';<br />
	$key = 'super-secret-key';<br />
	<br />
	$encrypted_string = $this->encrypt->encode($msg, $key);</code>


	<h2>$this->encrypt->decode()</h2>

	<p>Decrypts an encoded string. Example:</p>

	<code>
	$encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84';<br />
	<br />
	$plaintext_string = $this->encrypt->decode($encrypted_string);</code>

	<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>

	<code>
	$msg = 'My secret message';<br />
	$key = 'super-secret-key';<br />
	<br />
	$encrypted_string = $this->encrypt->decode($msg, $key);</code>


	<h2>$this->encrypt->set_cipher();</h2>

	<p>Permits you to set an Mcrypt cipher. By default it uses <samp>MCRYPT_RIJNDAEL_256</samp>. Example:</p>
	<code>$this->encrypt->set_cipher(MCRYPT_BLOWFISH);</code>
	<p>Please visit php.net for a list of <a href="http://php.net/mcrypt">available ciphers</a>.</p>

	<p>If you'd like to manually test whether your server supports Mcrypt you can use:</p>
	<code>echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup';</code>


	<h2>$this->encrypt->set_mode();</h2>

	<p>Permits you to set an Mcrypt mode. By default it uses <samp>MCRYPT_MODE_ECB</samp>. Example:</p>
	<code>$this->encrypt->set_mode(MCRYPT_MODE_CFB);</code>
	<p>Please visit php.net for a list of <a href="http://php.net/mcrypt">available modes</a>.</p>


	<h2>$this->encrypt->sha1();</h2>
	<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>
	<code>$hash = $this->encrypt->sha1('Some string');</code>

	<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
	function:</p>

	<code>$hash = sha1('Some string');</code>

	<p>If your server does not support SHA1 you can use the provided function.</p>



	</div>
	<!-- END CONTENT -->


	<div id="footer">
	<p>
	Previous Topic:  <a href="email.html">Email Class</a>
	·
	<a href="#top">Top of Page</a>   ·
	<a href="../index.html">User Guide Home</a>   ·
	Next Topic:  <a href="file_uploading.html">File Uploading Class</a>
	</p>
	<p><a href="http://codeigniter.com">CodeIgniter</a>  ·  Copyright © 2006-2010  ·  <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
	</div>

	</body>
	</html>