Table of Contents
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 Crypt_TripleDES.
The Crypt_* functions require, minimally, PHP 4.0.0. Crypt_TripleDES additionally requires Crypt/DES.php.
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.
See php.net's entry on mcrypt_module_open.
The first parameter is equal to $algorithm_directory and the second, to $mode_directory.
Self-explanatory. Encrypts or decrypts messages. See the examples in the subsequent sections.
Say you have a 16-byte plaintext $plaintext and that you're using Crypt_DES. Using the default behavior, the two following code snippets
will yield different outputs:
echo $des->encrypt(substr($plaintext, 0, 8));
echo $des->encrypt(substr($plaintext, 8, 8));echo $des->encrypt($plaintext);
The solution is to enable the continuous buffer. Although this will resolve the above discrepancy, it creates another, as demonstrated with the following:
$des->encrypt(substr($plaintext, 0, 8));
echo $des->decrypt($des->encrypt(substr($plaintext, 8, 8)));echo $des->decrypt($des->encrypt(substr($plaintext, 8, 8)));
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 Crypt_DES() 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.
Implements DES (a block cipher). Here's an example of how to use it:
<?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));
?>
The constructor takes one optional parameter - $mode. $mode can be equal to CRYPT_DES_MODE_ECB
or CRYPT_DES_MODE_CBC. CRYPT_DES_MODE_CBC is generally considered more secure
and is what Crypt_DES uses by default. If you don't know the difference between ECB or CBC,
just use the default settings.
Implements TripleDES (a block cipher). Here's an example of how to use it:
<?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));
?>
The constructor takes one optional parameter - $mode. $mode can be equal to CRYPT_DES_MODE_ECB,
CRYPT_DES_MODE_CBC, CRYPT_DES_MODE_3CBC, or CRYPT_DES_MODE_CBC3.
CRYPT_DES_MODE_CBC3 is an alias CRYPT_DES_MODE_CBC. It's defined to distinguish
it from CRYPT_DES_MODE_3CBC, which uses inner chaining to propogate the initialization vector.
SSH-1 uses this and it is generally considered to be less secure then CRYPT_DES_MODE_CBC3,
which uses outer chaining (and is what SSH-2 uses).
Implements RC4 (a stream cipher). Here's an example of how to use it:
<?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));
?>Implements Rijndael / AES. Here's an example of how to use Crypt_AES:
<?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));
?>
Crypt_AES's constructor takes CRYPT_AES_MODE_ECB and CRYPT_AES_MODE_CBC as parameters. Crypt_Rijndael, CRYPT_RIJNDAEL_MODE_ECB and CRYPT_RIJNDAEL_MODE_CBC. In both cases, if no valid mode is defined, CBC will be used.
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.
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.
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).
If setKeyLength() 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.
setBlockLength() operates in a manner similar to setKeyLength(), with one exception. setBlockLength() only works on Rijndael. Although Crypt_AES inherits setBlockLength() as a function, the function doesn't do anything in AES.
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.
Table 3.1. AES Speed Comparisons
| movable-type.phps | phpaes.phps | phpclasses1.phps | phpclasses2.phps | phpseclib-aes.phps | phpseclib-rijndael.phps |
|---|---|---|---|---|---|
| 15.6844158172 | 39.9537248135 | 15.0100150108 | 62.591713190079 | 3.5728311081 | 5.24388728142 |
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.