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.
Self-explanatory. Encrypts or decrypts messages. See the examples in the subsequent sections.
If the continuous buffer is enabled and you're using a stream cipher or a block cipher mode other than ECB then encrypting the same string twice will yield different ciphertexts. The reason being that the IV doesn't reset after each encryption / decryption round when the continuous buffer is used. This provides better security but it may also make for less intuitive behavior. For this reason, the continuous buffer is disabled by default.
Enables / disables PKCS padding on block ciphers. Stream ciphers (Crypt_RC4 is the only stream
cipher currently included) ignore this.
Most stream ciphers (and block ciphers operating in a mode - like CTR - that turns them into stream ciphers) work by generating a stream of pseudorandom characters called a keystream and then XOR'ing that with the plaintext.
This *effectively* makes them one-time pads which, in theory, can provide perfect secrecy. The problem with one-time pads is that they're not as versatile as one might desire.
Among other things, a keystream must never be reset, lest it be possible for an attacker to recover the keystream via a known-plaintext attack. ie. $ciphertext ^ $plaintext = $key. If $key is constant (because the keystream's being reset or something) than an attacker can recover any $plaintext, but if not - if it's dynamic - then the only key that an attacker could recover is their own.
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));
?>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. Valid values for $mode are as follows:
CRYPT_DES_MODE_ECBCRYPT_DES_MODE_CBC3: Employs outer chaining to propogate the initialization vector. Used by SSH-2 and generally considered more secure than inner chaining.CRYPT_DES_MODE_3CBC: Employs inner chaining to propogate the initialization vector. Used by SSH-1.CRYPT_DES_MODE_CBC: The default value. An alias for CRYPT_DES_MODE_CBC3.CRYPT_DES_MODE_CTRImplements 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's optional parameter can take the following values:
CRYPT_AES_MODE_ECBCRYPT_AES_MODE_CBC: The default value.CRYPT_AES_MODE_CTR
Crypt_Rijndael takes the following:
CRYPT_RIJNDAEL_MODE_ECBCRYPT_RIJNDAEL_MODE_CBC: The default value.CRYPT_RIJNDAEL_MODE_CTRAES is a subset of Rijndael. Both have variable key sizes, however, AES's block size is fixed at 128 bits, 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 | 2.03581542968752 | 2.62501101493836 |
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. Note that if mcrypt weren't explicitily disabled phpseclib would have been even faster.