<html>
<head>
<title>crypt.html</title>
<meta http-equiv="content-type"
content="text/html; charset=ISO-8859-1">
</head>
<body>
<b><big><big>Crypt Class Documentation</big></big></b><br>
v. 1.0 by Jason Sheets <a href="mailto:hide@address.com"><hide@address.com></a><br>
<br>
Nov. 24 2002 1:00 PM MST<br>
<br>
Introduction<br>
<blockquote><a href="#What_is_Crypt_Class">What is Crypt Class?</a><br>
<a href="#Why_would_I_use_Crypt_Class">Why would I use Crypt Class?</a><br>
<a href="#What_Are_the_Requirements_of_Crypt">What are the Requirements?</a><br>
<a href="#What_License_is_Crypt_Class_distributed">What License is Crypt
Class distributed under?</a><br>
<br>
</blockquote>
Installation<br>
<blockquote><a href="#Installing_Crypt_Class">Installing Crypt Class</a><br>
</blockquote>
Using Crypt Class:<br>
<br>
<blockquote> Examples:<br>
<blockquote><a href="#Compression_Example">Compression Example</a><br>
<a href="#File_Example_1">File Example #1</a><br>
<a href="#String_Example_1">String Example #1</a><br>
</blockquote>
API Reference:<br>
</blockquote>
<blockquote>
<blockquote><a href="#clear_key">clear_key()</a><br>
<a href="#clear_filters">clear_filters();</a><br>
<a href="#clear_pre_encrypt_filter">clear_pre_encrypt_filter()</a><br>
<a href="#clear_post_decrypt_filter">clear_post_decrypt_filter()</a><br>
<a href="#decryptdata">decrypt($data)</a><br>
<a href="#decrypt_filesourcefile_destfile">decrypt_file($sourcefile,
$destfile)</a><br>
<a href="#encryptdata">encrypt($data)</a><br>
<a href="#encrypt_filesourcefile_destfile">encrypt_file($sourcefile,
$destfile)</a><br>
<a href="#generate_key">generate_key()</a><br>
<a href="#get_cipher_">get_cipher()</a><br>
<a href="#get_key">get_key()</a><br>
<a href="#get_mode">get_mode()</a><br>
<a href="#get_post_decrypt_filter">get_post_decrypt_filter()</a><br>
<a href="#get_pre_encrypt_filter">get_pre_encrypt_filter()</a><br>
<a href="#md5string">md5($string)</a><br>
<a href="#set_cipherciphername">set_cipher($ciphername)</a><br>
<a href="#sha1string">sha1($string)</a><br>
<a href="#set_keyencryptionkey">set_key($encryptionkey)</a><br>
<a href="#set_modeencryptionmode">set_mode($encryptionmode)</a><br>
<a href="#set_post_decrypt_filterfilter">set_post_decrypt_filter($filter)</a><br>
<a href="#set_pre_encrypt_filterfilter">set_pre_encrypt_filter($filter)</a><br>
<br>
</blockquote>
</blockquote>
Getting Help<br>
<blockquote><a href="#Contacting_the_Author">Contacting the Author</a><br>
</blockquote>
<br>
<a name="What_is_Crypt_Class"></a><b>What is Crypt Class?</b><br>
<blockquote>Crypt Class is a PHP class that is a wrapper around the PHP mcrypt_
functions. It greatly simplifies using encryption by combining multiple
steps into a few function calls. Crypt Class also automatically embeds
and extracts the IV from the encrypted data, removing this task from the developer.<br>
<br>
Because Crypt Class uses the mcrypt_ functions when you use Crypt Class you
are using true encryption ciphers and modes. Many times programmers
will create "encryption" ciphers, but in reality they are simply compressing
or scrambling data, this is not encryption and is not secure.<br>
<br>
Crypt Class also has the ability to compress your data before it encrypts
it, this many times results in encrypted data that is smaller than unencrypted
data!<br>
</blockquote>
<a name="Why_would_I_use_Crypt_Class"></a><b>Why would I use Crypt Class?</b><br>
<blockquote>The PHP developer would use Crypt Class to securely store or transmit
sensitive information, this includes any and all confidential information
that one would normally like to keep secret. Crypt Class should be seen
as an interface to the PHP encryption functions and used whenever encryption
is desired.<br>
</blockquote>
<a name="What_Are_the_Requirements_of_Crypt"></a><br>
<b>What Are the Requirements of Crypt Class?</b><br>
<blockquote>Crypt Class requires PHP 4 (4.1 or greater recommended) and the
mcrypt_ functions, this means PHP must be compiled --with-mcrypt, see the
<a href="http://www.php.net/mcrypt">PHP Manual</a> for more information.<br>
<br>
If you want to use compression you need to compile PHP --with-zlib or --with-bz2
(again see the PHP manual).<br>
</blockquote>
<br>
<a name="What_License_is_Crypt_Class_distributed"></a><b>What License is Crypt
Class distributed under?</b><br>
<blockquote>Crypt Class is distributed under the BSD License, a copy of this
license is included in the distribution, you can also view the license <a
href="http://www.opensource.org/licenses/bsd-license.php">online</a>.<br>
<br>
The BSD license was choosen because Crypt Class was created to increase security
and the author wants to ensure the widest usage possible. Additionally
the author believes the GPL and LGPL are too restrictive in their allowed
uses of derived works.<br>
</blockquote>
<br>
<b><a name="Installing_Crypt_Class"></a>Installing Crypt Class</b><br>
<blockquote>Crypt Class is easily installed, simply place crypt_class.php
with your PHP application's other files or in your PHP include path. <br>
<br>
</blockquote>
<b>Examples:</b><br>
<br>
<blockquote>All examples assume crypt_class.php is in the same directory as
the example PHP script.<br>
</blockquote>
<blockquote><a name="Compression_Example"></a><b>Compression Example</b><br>
<blockquote>This example demonstrates using zlib to compress data before
encryptiong it. The example data is a string but the compression will
also work if encrypt_file and decrypt_file are used.<br>
</blockquote>
<blockquote> <?php<br>
<blockquote>// include main crypt class file<br>
require_once('./crypt_class.php');<br>
<br>
// create instance of CRYPT_CLASS<br>
$crypt = new CRYPT_CLASS;<br>
<br>
// set the encryption cipher<br>
$crypt->set_cipher('twofish');<br>
<br>
// set encryption mode<br>
$crypt->set_mode('cfb');<br>
<br>
// set the encryption key<br>
$crypt->set_key('encryption key');<br>
<br>
// use zlib compression on data<br>
$crypt->set_pre_encrypt_filter('gzdeflate');<br>
$crypt->set_post_decrypt_filter('gzinflate');<br>
<br>
// example data<br>
$data = 'This is a string that we want to encrypt';<br>
<br>
// encrypt the data<br>
$enc_data = $crypt->encrypt($data);<br>
<br>
// decrypt the data<br>
$dec_data = $crypt->decrypt($data);<br>
</blockquote>
?><br>
</blockquote>
<blockquote></blockquote>
</blockquote>
<blockquote><a name="File_Example_1"></a><b>File Example #1</b><br>
<blockquote>This example demonstrates how to encrypt and decrypt a file.<br>
</blockquote>
<blockquote><?php<br>
<blockquote>// include main crypt class file<br>
require_once('./crypt_class.php');<br>
<br>
// create instance of CRYPT_CLASS<br>
$crypt = new CRYPT_CLASS;<br>
<br>
// set the encryption cipher<br>
$crypt->set_cipher('twofish');<br>
<br>
// set encryption mode<br>
$crypt->set_mode('cbc');<br>
<br>
// set the encryption key<br>
$crypt->set_key('encryption key');<br>
<br>
// encrypt /www/plain.txt to /www/plain-encrypted.txt<br>
$crypt->encrypt_file('/www/plain.txt', '/www/plain-encrypted.txt');<br>
<br>
// decrypt /www/plain-encrypted.txt to /www/plain-decrypted.txt<br>
$crypt->decrypt_file('/www/plain-encrypted.txt', '/www/plain-decrypted.txt');<br>
</blockquote>
?><br>
</blockquote>
<a name="String_Example_1"></a><br>
<b>String Example #1</b><br>
<blockquote>This example demonstrates how to encrypt and decrypt a string.<br>
</blockquote>
<blockquote><?php<br>
<blockquote>// include main crypt class file<br>
require_once('./crypt_class.php');<br>
<br>
// create instance of CRYPT_CLASS<br>
$crypt = new CRYPT_CLASS;<br>
<br>
// set the encryption cipher<br>
$crypt->set_cipher('twofish');<br>
<br>
// set encryption mode<br>
$crypt->set_mode('cfb');<br>
<br>
// set the encryption key<br>
$crypt->set_key('encryption key');<br>
<br>
// example data<br>
$data = 'This is a string that we want to encrypt';<br>
<br>
// encrypt the data<br>
$enc_data = $crypt->encrypt($data);<br>
<br>
// decrypt the data<br>
$dec_data = $crypt->decrypt($data);<br>
</blockquote>
?><br>
</blockquote>
</blockquote>
API Reference:<br>
<blockquote><b><a name="clear_key"></a>clear_key()</b><br>
<blockquote>Unsets the current encryption key.<br>
</blockquote>
<b><a name="clear_filters"></a>clear_filters();</b><br>
<blockquote>Clears both the pre_encrypt and post_decrypt filters, alternatively
call both clear_pre_encrypt_filter() and clear_post_decrypt_filter().<br>
</blockquote>
<b><a name="clear_pre_encrypt_filter"></a>clear_pre_encrypt_filter()</b><br>
<blockquote>Clears the pre_encrypt_filter, use if you no longer want the
current filter to apply.<br>
</blockquote>
<b><a name="clear_post_decrypt_filter"></a>clear_post_decrypt_filter()</b><br>
<blockquote>Clears the post_decrypt_filter, use if you no longer want the
current filter to apply.</blockquote>
<b><a name="decryptdata"></a>decrypt($data)</b><br>
<blockquote>Decrypts and returns the encrypted string $data.<br>
<br>
You must set_cipher, set_mode and set_key before calling this function.<br>
</blockquote>
<b><a name="decrypt_filesourcefile_destfile"></a>decrypt_file($sourcefile,
$destfile)</b><br>
<blockquote>Decrypts the encrypted file $sourcefile into $destfile, PHP
must have write access to $destfile.<br>
<br>
You must set_cipher, set_mode, and set_key before calling this function.<br>
</blockquote>
<b><a name="encryptdata"></a>encrypt($data)</b><br>
<blockquote>Encrypts the string $data.<br>
<br>
You must set_cipher, set_mode, and set_key before calling this function.<br>
</blockquote>
<b><a name="encrypt_filesourcefile_destfile"></a>encrypt_file($sourcefile,
$destfile)</b><br>
<blockquote>Encrypts the file $sourcefile and stores it in $destfile, PHP
must have write access to $destfile.<br>
<br>
You must set_cipher, set_mode, and set_key before calling this function.<br>
</blockquote>
<b><a name="generate_key"></a>generate_key()<br>
</b>
<blockquote>Attempts to generate a secure, random encryption key. This
key will not be easy to remember so<br>
it is recommended you use this function where scripts need to generate a key,
not where a user<br>
needs to remember it.<br>
<br>
This function will return a key for you to call set_key with.</blockquote>
<b><a name="get_cipher_"></a>get_cipher()</b><br>
<blockquote>Returns the current cipher name.<br>
</blockquote>
<b><a name="get_key"></a>get_key()</b><br>
<blockquote>Returns the current encryption key.<br>
</blockquote>
<b><a name="get_mode"></a>get_mode()</b><br>
<blockquote>Returns the current encryption mode (cbc, cfb, etc) name.<br>
</blockquote>
<b><a name="get_post_decrypt_filter"></a>get_post_decrypt_filter()</b><br>
<blockquote>Returns the current post_decrypt filter (i.e. gzinflate) function
name.<br>
</blockquote>
<b><a name="get_pre_encrypt_filter"></a>get_pre_encrypt_filter()</b><br>
<blockquote>Returns the current pre_encrypt filter (i.e. gzdeflate) function
name.<br>
</blockquote>
<b><a name="md5string"></a>md5($string)</b><br>
<blockquote>Returns the MD5 hash of $string, by default this will only work
if you have md5 defined as a function (PHP 4 does by default).<br>
<br>
This function is provided for convienance and to allow you to implement your
own MD5 hash without changing your code.<br>
</blockquote>
<b><a name="set_cipherciphername"></a>set_cipher($ciphername)</b><br>
<blockquote>Sets the encryption cipher, see <a
href="http://www.php.net/mcrypt">http://www.php.net/mcrypt</a> for more information.<br>
</blockquote>
<b><a name="sha1string"></a>sha1($string)</b><br>
<blockquote>Returns the SHA-1 hash of $string, by default this will only
work if you have sha1 defined as a function (PHP 4.3.0 or greater)<br>
<br>
This function is provided for convienance and to allow you to implement your
own SHA-1 hash without changing your code.<br>
</blockquote>
<b><a name="set_keyencryptionkey"></a>set_key($encryptionkey)</b><br>
<blockquote>Sets the encryption key to the provided string.<br>
<br>
You must set_key before encrypting or decrypting data.<br>
</blockquote>
<b><a name="set_modeencryptionmode"></a>set_mode($encryptionmode)</b><br>
<blockquote>Sets the encryption mode, refer to <a
href="http://www.php.net/mcrypt">http://www.php.net/mcrypt</a> for a list
of encryption modes.<br>
<br>
You should use cfb for string data and cbc for files.<br>
</blockquote>
<b><a name="set_post_decrypt_filterfilter"></a>set_post_decrypt_filter($filter)</b><br>
<blockquote>Sets the post_decrypt_filter, this is used to filter data after
it is decrypted.<br>
<br>
An example filter would be gzinflate, this would allow decompressing encrypted,
compressed data.<br>
</blockquote>
<b><a name="set_pre_encrypt_filterfilter"></a>set_pre_encrypt_filter($filter)</b><br>
<br>
<blockquote>Sets the pre_encrypt_filter, this is used to filter data before
it is encrypted.<br>
<br>
An example would be gzdeflate which would compress data before encrypting
it.<br>
</blockquote>
</blockquote>
<br>
<a name="Contacting_the_Author"></a>Contacting the Author<br>
<blockquote>Jason Sheets can be contacted by email at <a
href="mailto:hide@address.com?subject=Crypt%20Class">hide@address.com</a>
or <a href="mailto:hide@address.com?subject=Crypt%20Class">hide@address.com</a><br>
</blockquote>
<blockquote><br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
</blockquote>
<br>
</body>
</html>