library/phpsec/crypt.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 3. Cryptography</title><link rel="stylesheet" href="docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="PHP Secure Communications Library" /><link rel="up" href="index.html" title="PHP Secure Communications Library" /><link rel="prev" href="math.html" title="Chapter 2. Math" /><link rel="next" href="net.html" title="Chapter 4. Networking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Cryptography</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="math.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="net.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="crypt"></a>Chapter 3. Cryptography</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="crypt.html#crypt_intro">3.1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="crypt.html#crypt_dependencies">3.1.1. Dependencies</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_set">3.1.2. setKey() and setIV()</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_setmcrypt">3.1.3. setMCrypt()</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_encrypt">3.1.4. encrypt() and decrypt()</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_continuousbuffer">3.1.5. enableContinuousBuffer() and disableContinuousBuffer()</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_padding">3.1.6. enablePadding() and disablePadding()</a></span></dt></dl></dd><dt><span class="section"><a href="crypt.html#crypt_des">3.2. Crypt_DES</a></span></dt><dd><dl><dt><span class="section"><a href="crypt.html#crypt_des_constructor">3.2.1. The constructor</a></span></dt></dl></dd><dt><span class="section"><a href="crypt.html#crypt_tripledes">3.3. Crypt_TripleDES</a></span></dt><dd><dl><dt><span class="section"><a href="crypt.html#crypt_tripledes_constructor">3.3.1. The constructor</a></span></dt></dl></dd><dt><span class="section"><a href="crypt.html#crypt_rc4">3.4. Crypt_RC4</a></span></dt><dd><dl><dt><span class="section"><a href="crypt.html#crypt_rc4_constructor">3.4.1. The constructor</a></span></dt></dl></dd><dt><span class="section"><a href="crypt.html#crypt_aes">3.5. Crypt_Rijndael &amp; Crypt_AES</a></span></dt><dd><dl><dt><span class="section"><a href="crypt.html#crypt_aes_constructor">3.5.1. The constructor</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_aes_vs_rijndael">3.5.2. AES vs. Rijndael</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_aes_setkeylength">3.5.3. setKeyLength()</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_aes_setblocklength">3.5.4. setBlockLength()</a></span></dt><dt><span class="section"><a href="crypt.html#crypt_aes_benchmarks">3.5.5. Speed Comparisons</a></span></dt></dl></dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="crypt_intro"></a>3.1. Introduction</h2></div></div></div><p>
   4                 All of the cryptographic libraries included in phpseclib use mcrypt, if available, and an internal implementation
   5                 if it's not.  The libraries all use a common interface although some functions, for some algorithms, carry with
   6                 with them certain caveats.  Those that do not have caveats attached (or have relatively few attached) are
   7                 described below.  If you don't know which one to use, try <code class="code">Crypt_TripleDES</code>.
   8             </p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_dependencies"></a>3.1.1. Dependencies</h3></div></div></div><p>
   9                     The Crypt_* functions require, minimally, PHP 4.0.0.  Crypt_TripleDES additionally requires Crypt/DES.php.
  10                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_set"></a>3.1.2. setKey() and setIV()</h3></div></div></div><p>
  11                     Sets the key and the initialization vector, respectively.  If neither are set, each assumed to be equal to
  12                     some amount of null bytes.  The initialization vector is only used in block ciphers and even then only
  13                     in CBC mode.  If the key or the initialization vector are larger then the block size, they're truncated.
  14                     If they're smaller, they're padded with null bytes.
  15                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_setmcrypt"></a>3.1.3. setMCrypt()</h3></div></div></div><p>
  16                     See php.net's entry on <a class="ulink" href="http://php.net/function.mcrypt-module-open#function.mcrypt-module-open" target="_top">mcrypt_module_open</a>.
  17                     The first parameter is equal to <code class="code">$algorithm_directory</code> and the second, to <code class="code">$mode_directory</code>.
  18                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_encrypt"></a>3.1.4. encrypt() and decrypt()</h3></div></div></div><p>
  19                     Self-explanatory.  Encrypts or decrypts messages.  See the examples in the subsequent sections.
  20                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_continuousbuffer"></a>3.1.5. enableContinuousBuffer() and disableContinuousBuffer()</h3></div></div></div><p>
  21                     Say you have a 16-byte plaintext $plaintext and that you're using <code class="code">Crypt_DES</code>.  Using the default behavior, the two following code snippets
  22                     will yield different outputs:
  23                 </p><pre class="programlisting">    echo $des-&gt;encrypt(substr($plaintext, 0, 8));
  24     echo $des-&gt;encrypt(substr($plaintext, 8, 8));</pre><pre class="programlisting">    echo $des-&gt;encrypt($plaintext);</pre><p>
  25                     The solution is to enable the continuous buffer.  Although this will resolve the above discrepancy, it creates
  26                     another, as demonstrated with the following:
  27                 </p><pre class="programlisting">    $des-&gt;encrypt(substr($plaintext, 0, 8));
  28     echo $des-&gt;decrypt($des-&gt;encrypt(substr($plaintext, 8, 8)));</pre><pre class="programlisting">    echo $des-&gt;decrypt($des-&gt;encrypt(substr($plaintext, 8, 8)));</pre><p>
  29                     With the continuous buffer disabled, these would yield the same output.  With it enabled, they yield different
  30                     outputs.  The reason is due to the fact that the initialization vector's change after every encryption /
  31                     decryption round when the continuous buffer is enabled.  When it's disabled, they remain constant.
  32
  33                     Put another way, when the continuous buffer is enabled, the state of the <code class="code">Crypt_DES()</code> object changes after each
  34                     encryption / decryption round, whereas otherwise, it'd remain constant.  For this reason, it's recommended that
  35                     continuous buffers not be used.  They do offer better security and are, in fact, sometimes required (SSH uses them),
  36                     however, they are also less intuitive and more likely to cause you problems.
  37                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_padding"></a>3.1.6. enablePadding() and disablePadding()</h3></div></div></div><p>
  38                     Enables / disables PKCS padding on block ciphers.  Stream ciphers (<code class="code">Crypt_RC4</code> is the only stream
  39                     cipher currently included) ignore this.
  40                 </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="crypt_des"></a>3.2. Crypt_DES</h2></div></div></div><p>
  41                 Implements DES (a block cipher).  Here's an example of how to use it:
  42             </p><pre class="programlisting">&lt;?php
  43     include('Crypt/DES.php');
  44
  45     $des = new Crypt_DES();
  46
  47     $des-&gt;setKey('abcdefgh');
  48
  49     $size = 10 * 1024;
  50     $plaintext = '';
  51     for ($i = 0; $i &lt; $size; $i++) {
  52         $plaintext.= 'a';
  53     }
  54
  55     echo $des-&gt;decrypt($des-&gt;encrypt($plaintext));
  56 ?&gt;</pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_des_constructor"></a>3.2.1. The constructor</h3></div></div></div><p>
  57                     The constructor takes one optional parameter - $mode.  $mode can be equal to <code class="code">CRYPT_DES_MODE_ECB</code>
  58                     or <code class="code">CRYPT_DES_MODE_CBC</code>.  <code class="code">CRYPT_DES_MODE_CBC</code> is generally considered more secure
  59                     and is what <code class="code">Crypt_DES</code> uses by default.  If you don't know the difference between ECB or CBC,
  60                     just use the default settings.
  61                 </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="crypt_tripledes"></a>3.3. Crypt_TripleDES</h2></div></div></div><p>
  62                 Implements TripleDES (a block cipher).  Here's an example of how to use it:
  63             </p><pre class="programlisting">&lt;?php
  64     include('Crypt/TripleDES.php');
  65
  66     $des = new Crypt_TripleDES();
  67
  68     $des-&gt;setKey('abcdefghijklmnopqrstuvwx');
  69
  70     $size = 10 * 1024;
  71     $plaintext = '';
  72     for ($i = 0; $i &lt; $size; $i++) {
  73         $plaintext.= 'a';
  74     }
  75
  76     echo $des-&gt;decrypt($des-&gt;encrypt($plaintext));
  77 ?&gt;</pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_tripledes_constructor"></a>3.3.1. The constructor</h3></div></div></div><p>
  78                     The constructor takes one optional parameter - $mode.  $mode can be equal to <code class="code">CRYPT_DES_MODE_ECB</code>,
  79                     <code class="code">CRYPT_DES_MODE_CBC</code>, <code class="code">CRYPT_DES_MODE_3CBC</code>, or <code class="code">CRYPT_DES_MODE_CBC3</code>.
  80                     <code class="code">CRYPT_DES_MODE_CBC3</code> is an alias <code class="code">CRYPT_DES_MODE_CBC</code>.  It's defined to distinguish
  81                     it from <code class="code">CRYPT_DES_MODE_3CBC</code>, which uses inner chaining to propogate the initialization vector.
  82                     SSH-1 uses this and it is generally considered to be less secure then <code class="code">CRYPT_DES_MODE_CBC3</code>,
  83                     which uses outer chaining (and is what SSH-2 uses).
  84                 </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="crypt_rc4"></a>3.4. Crypt_RC4</h2></div></div></div><p>
  85                 Implements RC4 (a stream cipher).  Here's an example of how to use it:
  86             </p><pre class="programlisting">&lt;?php
  87     include('Crypt/RC4.php');
  88
  89     $rc4 = new Crypt_RC4();
  90
  91     $rc4-&gt;setKey('abcdefghijklmnopqrstuvwx');
  92
  93     $size = 10 * 1024;
  94     $plaintext = '';
  95     for ($i = 0; $i &lt; $size; $i++) {
  96         $plaintext.= 'a';
  97     }
  98
  99     echo $rc4-&gt;decrypt($rc4-&gt;encrypt($plaintext));
 100 ?&gt;</pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_rc4_constructor"></a>3.4.1. The constructor</h3></div></div></div><p>
 101                     Not much to say about this constructor.  Since it's a stream cipher, you don't need to worry about which
 102                     mode of operation to use.
 103                 </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="crypt_aes"></a>3.5. Crypt_Rijndael &amp; Crypt_AES</h2></div></div></div><p>
 104                 Implements Rijndael / AES.  Here's an example of how to use Crypt_AES:
 105             </p><pre class="programlisting">&lt;?php
 106     include('Crypt/AES.php');
 107
 108     $aes = new Crypt_AES();
 109
 110     $aes-&gt;setKey('abcdefghijklmnop');
 111
 112     $size = 10 * 1024;
 113     $plaintext = '';
 114     for ($i = 0; $i &lt; $size; $i++) {
 115         $plaintext.= 'a';
 116     }
 117
 118     echo $aes-&gt;decrypt($aes-&gt;encrypt($plaintext));
 119 ?&gt;</pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_aes_constructor"></a>3.5.1. The constructor</h3></div></div></div><p>
 120                     <code class="code">Crypt_AES</code>'s constructor takes <code class="code">CRYPT_AES_MODE_ECB</code> and <code class="code">CRYPT_AES_MODE_CBC</code> as parameters.  <code class="code">Crypt_Rijndael</code>, <code class="code">CRYPT_RIJNDAEL_MODE_ECB</code> and <code class="code">CRYPT_RIJNDAEL_MODE_CBC</code>.  In both cases, if no valid mode is defined, CBC will be used.
 121                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_aes_vs_rijndael"></a>3.5.2. AES vs. Rijndael</h3></div></div></div><p>
 122                     AES is a subset of Rijndael.  Both have variable key sizes, however, AES's block size is fixed at 128 bytes, whereas Rijndael's is variable.  Also, Rijndael supports, by means of an extension to the specification, two key sizes that AES does not - 160 bits and 224 bits.
 123                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_aes_setkeylength"></a>3.5.3. setKeyLength()</h3></div></div></div><p>
 124                     Valid key lengths for AES are 128 bits, 192 bits, and 256 bits.  If the key that is assigned is invalid and less than 256 bits, they key length is rounded up to the next closest valid size and the key will be null padded to that amount.  If the key length is greater than 256 bits, it will be truncated to 256 bits.
 125                 </p><p>
 126                     As an example, if the key is 136 bits, it will be null padded to 192 bits (or 160 bits if Rijndael is being used).
 127                 </p><p>
 128                     If <code class="code">setKeyLength()</code> has been called, this behavior changes somewhat.  Say you've set the key length, via this function, to 256 bits.  Then, instead of an invalid key being null padded to 192 or 160 bits, it will be null padded to 256 bits.
 129                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_aes_setblocklength"></a>3.5.4. setBlockLength()</h3></div></div></div><p>
 130                     <code class="code">setBlockLength()</code> operates in a manner similar to <code class="code">setKeyLength()</code>, with one exception.  <code class="code">setBlockLength()</code> only works on Rijndael.  Although <code class="code">Crypt_AES</code> inherits <code class="code">setBlockLength()</code> as a function, the function doesn't do anything in AES.
 131                 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="crypt_aes_benchmarks"></a>3.5.5. Speed Comparisons</h3></div></div></div><p>
 132                     The following table compares the speed of five different pure-PHP implementations of AES (one of which is Crypt_Rijndael and one of which is Crypt_AES) when ran on 150KB of text on a 1.8GHz Pentium 4-M.  The numbers listed are averaged from five different trials and are measured in seconds.  phpseclib's two implementations are highlighted.  All implementations can be viewed by clicking on their names.
 133                 </p><div class="table"><a id="crypt_aes_benchmarks_table"></a><p class="title"><b>Table 3.1. AES Speed Comparisons</b></p><div class="table-contents"><table summary="AES Speed Comparisons" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/movable-type.phps" target="_top">movable-type.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpaes.phps" target="_top">phpaes.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpclasses1.phps" target="_top">phpclasses1.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpclasses2.phps" target="_top">phpclasses2.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpseclib-aes.phps" target="_top">phpseclib-aes.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpseclib-rijndael.phps" target="_top">phpseclib-rijndael.phps</a></th></tr></thead><tbody><tr><td align="right">15.6844158172</td><td align="right">39.9537248135</td><td align="right">15.0100150108</td><td align="right">62.591713190079</td><td class="highlight" align="right">3.5728311081</td><td class="highlight" align="right">5.24388728142</td></tr></tbody></table></div></div><br class="table-break" /><p>
 134                     As can be seen, phpseclib's implementations are the fastest.  phpseclib-aes.phps is faster than phpseclib-rijndael.phps because phpseclib-rijndael.phps has to contend with multiple block sizes whereas phpseclib-aes.phps does not.
 135                 </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="math.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="net.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Math </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Networking</td></tr></table></div></body></html>