Alexander Kampmann
136 lines
18 KiB
HTML
136 lines
18 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!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"><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 & 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>
|
||
All of the cryptographic libraries included in phpseclib use mcrypt, if available, and an internal implementation
|
||
if it's not. The libraries all use a common interface although some functions, for some algorithms, carry with
|
||
with them certain caveats. Those that do not have caveats attached (or have relatively few attached) are
|
||
described below. If you don't know which one to use, try <code class="code">Crypt_TripleDES</code>.
|
||
</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>
|
||
The Crypt_* functions require, minimally, PHP 4.0.0. Crypt_TripleDES additionally requires Crypt/DES.php.
|
||
</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>
|
||
Sets the key and the initialization vector, respectively. If neither are set, each assumed to be equal to
|
||
some amount of null bytes. The initialization vector is only used in block ciphers and even then only
|
||
in CBC mode. If the key or the initialization vector are larger then the block size, they're truncated.
|
||
If they're smaller, they're padded with null bytes.
|
||
</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>
|
||
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>.
|
||
The first parameter is equal to <code class="code">$algorithm_directory</code> and the second, to <code class="code">$mode_directory</code>.
|
||
</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>
|
||
Self-explanatory. Encrypts or decrypts messages. See the examples in the subsequent sections.
|
||
</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>
|
||
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
|
||
will yield different outputs:
|
||
</p><pre class="programlisting"> echo $des->encrypt(substr($plaintext, 0, 8));
|
||
echo $des->encrypt(substr($plaintext, 8, 8));</pre><pre class="programlisting"> echo $des->encrypt($plaintext);</pre><p>
|
||
The solution is to enable the continuous buffer. Although this will resolve the above discrepancy, it creates
|
||
another, as demonstrated with the following:
|
||
</p><pre class="programlisting"> $des->encrypt(substr($plaintext, 0, 8));
|
||
echo $des->decrypt($des->encrypt(substr($plaintext, 8, 8)));</pre><pre class="programlisting"> echo $des->decrypt($des->encrypt(substr($plaintext, 8, 8)));</pre><p>
|
||
With the continuous buffer disabled, these would yield the same output. With it enabled, they yield different
|
||
outputs. The reason is due to the fact that the initialization vector's change after every encryption /
|
||
decryption round when the continuous buffer is enabled. When it's disabled, they remain constant.
|
||
|
||
Put another way, when the continuous buffer is enabled, the state of the <code class="code">Crypt_DES()</code> object changes after each
|
||
encryption / decryption round, whereas otherwise, it'd remain constant. For this reason, it's recommended that
|
||
continuous buffers not be used. They do offer better security and are, in fact, sometimes required (SSH uses them),
|
||
however, they are also less intuitive and more likely to cause you problems.
|
||
</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>
|
||
Enables / disables PKCS padding on block ciphers. Stream ciphers (<code class="code">Crypt_RC4</code> is the only stream
|
||
cipher currently included) ignore this.
|
||
</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>
|
||
Implements DES (a block cipher). Here's an example of how to use it:
|
||
</p><pre class="programlisting"><?php
|
||
include('Crypt/DES.php');
|
||
|
||
$des = new Crypt_DES();
|
||
|
||
$des->setKey('abcdefgh');
|
||
|
||
$size = 10 * 1024;
|
||
$plaintext = '';
|
||
for ($i = 0; $i < $size; $i++) {
|
||
$plaintext.= 'a';
|
||
}
|
||
|
||
echo $des->decrypt($des->encrypt($plaintext));
|
||
?></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>
|
||
The constructor takes one optional parameter - $mode. $mode can be equal to <code class="code">CRYPT_DES_MODE_ECB</code>
|
||
or <code class="code">CRYPT_DES_MODE_CBC</code>. <code class="code">CRYPT_DES_MODE_CBC</code> is generally considered more secure
|
||
and is what <code class="code">Crypt_DES</code> uses by default. If you don't know the difference between ECB or CBC,
|
||
just use the default settings.
|
||
</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>
|
||
Implements TripleDES (a block cipher). Here's an example of how to use it:
|
||
</p><pre class="programlisting"><?php
|
||
include('Crypt/TripleDES.php');
|
||
|
||
$des = new Crypt_TripleDES();
|
||
|
||
$des->setKey('abcdefghijklmnopqrstuvwx');
|
||
|
||
$size = 10 * 1024;
|
||
$plaintext = '';
|
||
for ($i = 0; $i < $size; $i++) {
|
||
$plaintext.= 'a';
|
||
}
|
||
|
||
echo $des->decrypt($des->encrypt($plaintext));
|
||
?></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>
|
||
The constructor takes one optional parameter - $mode. $mode can be equal to <code class="code">CRYPT_DES_MODE_ECB</code>,
|
||
<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>.
|
||
<code class="code">CRYPT_DES_MODE_CBC3</code> is an alias <code class="code">CRYPT_DES_MODE_CBC</code>. It's defined to distinguish
|
||
it from <code class="code">CRYPT_DES_MODE_3CBC</code>, which uses inner chaining to propogate the initialization vector.
|
||
SSH-1 uses this and it is generally considered to be less secure then <code class="code">CRYPT_DES_MODE_CBC3</code>,
|
||
which uses outer chaining (and is what SSH-2 uses).
|
||
</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>
|
||
Implements RC4 (a stream cipher). Here's an example of how to use it:
|
||
</p><pre class="programlisting"><?php
|
||
include('Crypt/RC4.php');
|
||
|
||
$rc4 = new Crypt_RC4();
|
||
|
||
$rc4->setKey('abcdefghijklmnopqrstuvwx');
|
||
|
||
$size = 10 * 1024;
|
||
$plaintext = '';
|
||
for ($i = 0; $i < $size; $i++) {
|
||
$plaintext.= 'a';
|
||
}
|
||
|
||
echo $rc4->decrypt($rc4->encrypt($plaintext));
|
||
?></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>
|
||
Not much to say about this constructor. Since it's a stream cipher, you don't need to worry about which
|
||
mode of operation to use.
|
||
</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 & Crypt_AES</h2></div></div></div><p>
|
||
Implements Rijndael / AES. Here's an example of how to use Crypt_AES:
|
||
</p><pre class="programlisting"><?php
|
||
include('Crypt/AES.php');
|
||
|
||
$aes = new Crypt_AES();
|
||
|
||
$aes->setKey('abcdefghijklmnop');
|
||
|
||
$size = 10 * 1024;
|
||
$plaintext = '';
|
||
for ($i = 0; $i < $size; $i++) {
|
||
$plaintext.= 'a';
|
||
}
|
||
|
||
echo $aes->decrypt($aes->encrypt($plaintext));
|
||
?></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>
|
||
<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.
|
||
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div> |