Chapter 3. Symmetric-key Cryptography

Table of Contents

3.1. Introduction
3.1.1. Dependencies
3.1.2. setKey() and setIV()
3.1.3. encrypt() and decrypt()
3.1.4. enableContinuousBuffer() and disableContinuousBuffer()
3.1.5. enablePadding() and disablePadding()
3.1.6. A word of caution about stream ciphers and CTR mode
3.2. Crypt_DES
3.2.1. The constructor
3.3. Crypt_TripleDES
3.3.1. The constructor
3.4. Crypt_RC4
3.4.1. The constructor
3.5. Crypt_Rijndael & Crypt_AES
3.5.1. The constructor
3.5.2. AES vs. Rijndael
3.5.3. setKeyLength()
3.5.4. setBlockLength()
3.5.5. Speed Comparisons

3.1. Introduction

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.

3.1.1. Dependencies

The Crypt_* functions require, minimally, PHP 4.0.0. Crypt_TripleDES additionally requires Crypt/DES.php.

3.1.2. setKey() and setIV()

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.

3.1.3. encrypt() and decrypt()

Self-explanatory. Encrypts or decrypts messages. See the examples in the subsequent sections.

3.1.4. enableContinuousBuffer() and disableContinuousBuffer()

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.

3.1.5. enablePadding() and disablePadding()

Enables / disables PKCS padding on block ciphers. Stream ciphers (Crypt_RC4 is the only stream cipher currently included) ignore this.

3.1.6. A word of caution about stream ciphers and CTR mode

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.

3.2. Crypt_DES

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));
?>

3.2.1. The constructor

The constructor takes one optional parameter - $mode. Valid values for $mode are as follows:

  • CRYPT_DES_MODE_ECB
  • CRYPT_DES_MODE_CBC: The default value.
  • CRYPT_DES_MODE_CTR

3.3. Crypt_TripleDES

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));
?>

3.3.1. The constructor

The constructor takes one optional parameter - $mode. Valid values for $mode are as follows:

  • CRYPT_DES_MODE_ECB
  • CRYPT_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_CTR

3.4. Crypt_RC4

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));
?>

3.4.1. The constructor

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.

3.5. Crypt_Rijndael & Crypt_AES

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));
?>

3.5.1. The constructor

Crypt_AES's constructor's optional parameter can take the following values:

  • CRYPT_AES_MODE_ECB
  • CRYPT_AES_MODE_CBC: The default value.
  • CRYPT_AES_MODE_CTR

Crypt_Rijndael takes the following:

  • CRYPT_RIJNDAEL_MODE_ECB
  • CRYPT_RIJNDAEL_MODE_CBC: The default value.
  • CRYPT_RIJNDAEL_MODE_CTR

3.5.2. AES vs. Rijndael

AES 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.

3.5.3. setKeyLength()

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.

3.5.4. setBlockLength()

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.

3.5.5. Speed Comparisons

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.phpsphpaes.phpsphpclasses1.phpsphpclasses2.phpsphpseclib-aes.phpsphpseclib-rijndael.phps
15.684415817239.953724813515.010015010862.5917131900792.035815429687522.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.