Frey Kuo

NAME

MCrypt - Perl extension for MCrypt Crypto library

DISCLAIMER

THIS IS A FIRST RELEASE BETA VERSION.

    Yes, it does work.

If you have use for this, please try and use it and report any bugs you find. Feedback from users of this module is important.

SYNOPSIS

  use MCrypt qw(:Functions :Modes :Types) ;
  my $key = "my secret key";
  my $data "this is my secret data";
  # optional IV that matches the blocksize of the cipher!
  my $iv = "12345678" ; # 8 bytes for MCRYPT_3DES
  $ciphertext = mcrypt_cbc( MCRYPT_3DES, $key, $data, MCRYPT_ENCRYPT, $iv ) ;

  **NOTE** Please read the section on EXPORT TAGS below for information on the MCRYPT_ constants and the how to conserve your namespace.

DEPENDENCIES

This interface is dependent on the 2.2.x tree of the MCRYPT library. Please download and install the latest libmcrypt-2.2.x.tar.gz at ftp://argeas.cs-net.gr/pub/unix/mcrypt. As of this writing, the latest is libmcrypt-2.2.7.tar.gz. Additional information about the mcrypt library can be found at http://mcrypt.hellug.gr.

Libmcrypt MUST be found in your library path when using this module. In Linux, libmcrypt is defaultly installed in /usr/local/lib -- in this case, be sure that the /usr/local/lib path is in your /etc/ld.so.conf.

DESCRIPTION

This is an perl interface to the MCrypt crypto library, which supports a wide variety of block algorithms such as DES, TripleDES, Blowfish (default), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2, GOST, LOKI, SERPENT, CAST and RIJNDAEL in CBC, OFB, CFB and ECB cipher modes.

Mcrypt can be used to encrypt and decrypt using the above mentioned ciphers. The four important mcrypt commands (mcrypt_cfb(), mcrypt_cbc(), mcrypt_ecb(), and mcrypt_ofb()) can operate in both modes which are named MCRYPT_ENCRYPT and MCRYPT_DECRYPT, respectively.

Mcrypt can operate in four block cipher modes (CBC, OFB, CFB, and ECB). We will outline the normal use for each of these modes. For a more complete reference and discussion see Applied Cryptography by Schneier (ISBN 0-471-11709-9).

      ECB (electronic codebook) is suitable for random data, such as encrypting other keys. Since data there is short and random, the disadvantages of ECB have a favorable negative effect. 

      CBC (cipher block chaining) is especially suitable for encrypting files where the security is increased over ECB significantly. 

      CFB (cipher feedback) is the best mode for encrypting byte streams where single bytes must be encrypted. 

      OFB (output feedback, in 8bit) is comparable to CFB, but can be used in applications where error propagation cannot be tolerated. It's insecure (because it operates in 8bit mode) so it is not recommended to use it. 

MCrypt does not support encrypting/decrypting bit streams currently. As of now, MCrypt only supports handling of strings.

Here is the list of cipher constants which are currently supported by the MCrypt module:

      MCRYPT_DES 

      MCRYPT_3DES 

      MCRYPT_3WAY

      MCRYPT_GOST

      MCRYPT_SAFER64 

      MCRYPT_SAFER128 

      MCRYPT_CAST_128 

      MCRYPT_CAST_256 

      MCRYPT_XTEA

      MCRYPT_RC2_128

      MCRYPT_RC2_192

      MCRYPT_RC2_1024

      MCRYPT_TWOFISH128

      MCRYPT_TWOFISH192 

      MCRYPT_TWOFISH256 

      MCRYPT_BLOWFISH_128

      MCRYPT_BLOWFISH_192

      MCRYPT_BLOWFISH_256

      MCRYPT_BLOWFISH_448 (the default if a blank cipher is supplied)

      MCRYPT_CAST_256

      MCRYPT_SAFERPLUS

      MCRYPT_LOKI97

      MCRYPT_SERPENT_128

      MCRYPT_SERPENT_192

      MCRYPT_SERPENT_256

      MCRYPT_RIJNDAEL_128

      MCRYPT_RIJNDAEL_192

      MCRYPT_RIJNDAEL_256

      MCRYPT_CRYPT

      MCRYPT_RC6_128

      MCRYPT_RC6_192

      MCRYPT_RC6_256

      MCRYPT_IDEA (non-free)

      MCRYPT_ARCFOUR (also aliased as MCRYPT_RC_4) 

You must (in CFB and OFB mode) or can (in CBC mode) supply an initialization vector (IV) to the respective cipher function. The IV must be unique and must be the same when decrypting/encrypting. With data which is stored encrypted, you can take the output of a function of the index under which the data is stored (e.g. the MD5 key of the filename). Alternatively, you can transmit the IV together with the encrypted data (see chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9) for a discussion of this topic).

EXPORT TAGS

  A more conservative usage of the above SYNOPSIS:

  # no export tags supplied in the below line; import :Functions by default
  use MCrypt ;
  my $key = "my secret key";
  my $data "this is my secret data";
  # optional IV that matches the blocksize of the cipher!
  my $iv = "12345678" ; # 8 bytes for MCRYPT_3DES
  $ciphertext = mcrypt_cbc( MCrypt::MCRYPT_3DES, $key, $data, MCrypt::MCRYPT_ENCRYPT, $iv ) ;
  

Functions This tag exports all the functions related to MCrypt. This tag should always be imported unless you are going to be calling MCrypt functions with the full package name. This tag is automatically imported if no export tags are supplied as in the above example. (i.e. MCrypt::mcrypt_cbc()).

Modes This tag exports the encryption mode constants MCRYPT_ENCRYPT and MCRYPT_DECRYPT. It is recommended that you import this tag as it only imports two constants into your namespace. If you are being conservative with your namespace, you can leave this out providing you call these constant with the package name. (i.e. MCrypt::MCRYPT_ENCRYPT )

Types This tag exports the cipher constants defined by the list of ciphers above in DESCRIPTION. It is recommended you import this tag for ease of use. If you are concerned with polluting your namespace, do not import this tag, and use the form MCrypt::MCRYPT_CIPHERNAME when supplying the cipher to the MCrypt functions. (i.e. MCrypt::MCRYPT_3DES )

PROGRAMMING FUNCTIONS AND METHODS

The following methods are available:

mcrypt_cbc()

 Mcrypt_cbc() encrypts or decrypts (depending on mode) the data with cipher and key in CBC cipher mode and returns the resulting string. 

   $ciphertext = mcrypt_cbc($cipher, $key, $data, $mode, [$IV]) ;

Cipher is one of the MCRYPT_ciphername constants.

Key is the key supplied to the algorithm. It must be kept secret.

Data is the data which shall be encrypted/decrypted.

Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

IV is the optional initialization vector. (This must be the blocksize of the cipher!)

mcrypt_ecb()

 Mcrypt_ecb() encrypts or decrypts (depending on mode) the data with cipher and key in ECB cipher mode and returns the resulting string. 

   $ciphertext = mcrypt_ecb($cipher, $key, $data, $mode) ;

Cipher is one of the MCRYPT_ciphername constants.

Key is the key supplied to the algorithm. It must be kept secret.

Data is the data which shall be encrypted/decrypted.

Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

mcrypt_ofb()

 Mcrypt_ofb() encrypts or decrypts (depending on mode) the data with cipher and key in OFB cipher mode and returns the resulting string. 

   $ciphertext = mcrypt_ofb($cipher, $key, $data, $mode, $IV) ;

Cipher is one of the MCRYPT_ciphername constants.

Key is the key supplied to the algorithm. It must be kept secret.

Data is the data which shall be encrypted/decrypted.

Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

IV is the initialization vector. (This must be the blocksize of the cipher!)

mcrypt_cfb()

 Mcrypt_cfb() encrypts or decrypts (depending on mode) the data with cipher and key in CFB cipher mode and returns the resulting string. 

   $ciphertext = mcrypt_cfb($cipher, $key, $data, $mode, $IV) ;

Cipher is one of the MCRYPT_ciphername constants.

Key is the key supplied to the algorithm. It must be kept secret.

Data is the data which shall be encrypted/decrypted.

Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

IV is the initialization vector. (This must be the blocksize of the cipher!)

mcrypt_get_cipher_name()

 Mcrypt_get_cipher_name() is used to get the name of the specified cipher.  This function takes the cipher number as an argument and returns the name of the cipher as a string or false, if the cipher does not exist.

   $ciphername = mcrypt_get_cipher_name( MCRYPT_3DES ) ;

Cipher is one of the MCRYPT_ciphername constants.

mcrypt_get_key_size()

 Mcrypt_get_key_size() is used to get the size of a key of the specified cipher.  This function takes one argument, the cipher and returns the size in bytes.  This function is useful to find the keysize for a specific cipher.  The key you use SHOULD match the keysize.

   $keysize = mcrypt_get_key_size( MCRYPT_3DES ) ;

Cipher is one of the MCRYPT_ciphername constants.

mcrypt_get_block_size()

 Mcrypt_get_block_size() is used to get the size of a block of the specified cipher.  This function takes one argument, the cipher and returns the size in bytes.   This function is useful for determining the correct size of the IV of a cipher.

   $keysize = mcrypt_get_block_size( MCRYPT_3DES ) ;

Cipher is one of the MCRYPT_ciphername constants.

TODO

 - More bug testing.
 - implement mcrypt_create_iv() in a nice way
 - detection of libmcrypt installation

AUTHOR

Kuo, Frey, kero@3SHEEP.COM.

CREDITS

Mavroyanopoulos, Nikos, <nmav@hellug.gr> - for the libmcrypt library.

Schumann, Sasha, <sascha@schumann.2ns.de> - for PHP's implementation of the libmcrypt interface.

SEE ALSO

mcrypt(3).