README

Path: README
Last Update: Sun Jul 29 18:32:22 +0200 2007

README for ruby-aes

=============

Ruby AES <rubyforge.org/projects/ruby-aes> is an implementation of the Rijndael algorithm.

Written by Alex Boussinet <alex.boussinet@gmail.com>

This release is mainly an import from the Ruby Application Archive (RAA). I‘ve added all the versions I was working on (algorithm variations) and a new C extension for improved performance. 6 variations are available:

  • "Normal":

Pure Ruby implementation of the Rijndael algorithm specifications. Useful for understanding the algorithm.

  • "Optimized":

Pure Ruby implementation based on the "Normal" code but optimized for speed. The SubBytes and ShiftRows methods have been combined.

  • "Table Optimized 1":

Pure Ruby implementation based on the C code from the Rijndael website. The arrays of constants are bigger because all the operations are already computed so it‘s mainly based on table look ups.

  • "Table Optimized 2":

Pure Ruby implementation based on the "Table Optimized 1" code. The arrays of constants are bigger because all the operations are already computed and table look ups are also combined.

  • "Table Unroll Optimized 1":

Pure Ruby implementation based on the "Table Optimized 1" code. The change here is that the loops are unrolled.

  • "Table Unroll Optimized 2":

Pure Ruby implementation based on the "Table Optimized 2" code. The change here is that the loops are unrolled.

  • "EXT Table Unroll Optimized 2":

C extension based on the "Table Unroll Optimized 2" code. This extension is provided for major speed improvement.

All those variations share the same API:

  Default key_length: 128
  Default mode: 'ECB'
  Default IV: 16 null chars ("00" * 16 in hex format)
  Default key: 16 null chars ("00" * 16 in hex format)
  Default input text: "PLAINTEXT"

  Aes.check_key(key_string, key_length)
  Aes.check_iv(iv_string)
  Aes.check_kl(key_length)
  Aes.check_mode(mode)
  Aes.init(key_length, mode, key, iv)
  Aes.encrypt_block(key_length, mode, key, iv, block) # no padding
  Aes.decrypt_block(key_length, mode, key, iv, block) # no padding
  Aes.encrypt_buffer(key_length, mode, key, iv, block) # padding
  Aes.decrypt_buffer(key_length, mode, key, iv, block) # padding
  Aes.encrypt_stream(key_length, mode, key, iv, sin, sout)
  Aes.decrypt_stream(key_length, mode, key, iv, sin, sout)
  Aes.bs() # block size for read operations (stream)
  Aes.bs=(bs)

Valid modes are:

    * ECB (Electronic Code Book)
    * CBC (Cipher Block Chaining)
    * OFB (Output Feedback)
    * CFB (Cipher Feedback)

Valid key length:

    * 128 bits
    * 192 bits
    * 256 bits

For a really good encryption, 256 bits CBC is recommanded.

For more information on AES-Rijndael, see: <csrc.nist.gov/encryption/aes/rijndael/>

[Validate]