cryptix
Class BlockCipher

java.lang.Object
  |
  +--cryptix.BlockCipher
Direct Known Subclasses:
IDEA

public abstract class BlockCipher
extends java.lang.Object

BlockCipher is an abstract superclass for ciphers that encrypt and decrypt a fixed length block with a fixed secret key. No memory of the text is kept between distinct operations (for memory behaviour, see streamCipher).

Usage of Extended Classes

General usage of extended classes is to construct the object, providing the secret key and any other details required. The key is generally fixed for any given object. Then, methods encrypt and decrypt are called with data for processing, always using the original key:

   String plain = "Et tu, Brute?";
   byte plainText[] = new byte[cryptor.blockLength];
   plain.getBytes(0, cryptor.blockLength, plainText, 0);
   
byte cipherText[] = new byte[cryptor.blockLength]; byte decrypText[] = new byte[cryptor.blockLength];
Caeser cryptor = new Caeser( 3 ); // 'a' becomes 'd', etc cryptor.encrypt( plainText, cipherText ); cryptor.decrypt( cipherText, decrypText );
String decryp = new String( decrypText, 0 ); String cipher = new String( cipherText, 0 );
if ( decryp.equals( plain ) && !cipher.equals( plain ) ) out.println( "Caeser is good for protecting secrets of state" ); else out.println( "Caeser has failed to keep secrets" );
In general, method encrypt takes plaintext and returns ciphertext, whilst method decrypt takes ciphertext and returns plaintext.

Adding New Ciphers

Extended classes should provide constructors that initialise the key and any other details:

   public final class Caeser extends BlockCipher
   {
       private static final String LIBRARY_NAME = "caeser";
       private int rotate = 3;        // 3 is caeser, 13 is "rot13"
       // public Caeser() { }         // default behaviour
       
public int blockLength() { return 8; }
/** * Create a Caeser object with a different rotation. * @param rotate number of positions to the right to adjust * / public Caeser( int rotate ) { this.rotate = rotate } ....
Whilst Caeser ciphers didn't deserve a real key, the amount of rotation for each character is almost as good. Note that the 'key' is fixed for the object; this is expected behaviour for extended classes, but not mandated.

Extended classes should provide methods blockEncrypt and blockDecrypt that operate on the passed data. The arrays in and out may be the same array. Methods encrypt and decrypt do not need to be provided as they call the former from within this super class:

       protected void
       blockEncrypt( byte in[], int in_offset, byte out[], int out_offset )
       {
           for (int i = 0; i < rotate; i++)
           {
               out[out_offset + i] = in[in_offset + i] + rotate;
               if ( out[out_offset + i] > (int)'Z' )   // modulo 26
                   out[out_offset + i] -= 26;          // only works on [A-Z]
           }
       }
 
Extended classes should document the algorithm, constructors, any special calls and any deviations from standard behaviour. Users can refer to this superclass for standard behavior.
        /**
         * Caeser is a substitution cipher recommended for Despots and jokes.
         * Warning: foreign characters will be thrown to the lions.
         * /
        public void Caeser
        ...
 

References

See also: Shakespeare, W., Julius Caeser, The Globe, and Schneier, B., Applied Cryptography, Wiley, 1996, 2nd Ed.

Copyright © 1995, 1996, 1997 Systemics Ltd on behalf of the Cryptix Development Team. All rights reserved.

See Also:
StreamCipher, SPEED, IDEA

Constructor Summary
BlockCipher()
           
 
Method Summary
protected abstract  void blockDecrypt(byte[] in, int in_offset, byte[] out, int out_offset)
          Perform a decryption in the extended class.
protected abstract  void blockEncrypt(byte[] in, int in_offset, byte[] out, int out_offset)
          Perform an encryption in the extended class.
abstract  int blockLength()
          Return the block length of this cipher.
 void decrypt(byte[] text)
          Decrypt a block of data in place.
 void decrypt(byte[] in, byte[] out)
          Decrypt a block of data.
 void decrypt(byte[] in, int in_offset, byte[] out, int out_offset)
          Decrypt a block of data within an array.
 void encrypt(byte[] text)
          Encrypt a block of data in place.
 void encrypt(byte[] in, byte[] out)
          Encrypt a block of data.
 void encrypt(byte[] in, int in_offset, byte[] out, int out_offset)
          Encrypt a block of data within an array.
abstract  int keyLength()
          Return the key length for this cipher.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BlockCipher

public BlockCipher()
Method Detail

encrypt

public final void encrypt(byte[] text)
Encrypt a block of data in place. The plaintext in text is encrypted and written back as ciphertext. The length of text must be the block length as returned by blockLength.

Parameters:
text - the buffer holding the data

decrypt

public final void decrypt(byte[] text)
Decrypt a block of data in place. The ciphertext in text is decrypted and written back as plaintext. The length of text must be the block length as returned by blockLength.

Parameters:
text - the buffer holding the data

encrypt

public final void encrypt(byte[] in,
                          byte[] out)
Encrypt a block of data. The plaintext in in is encrypted and the ciphertext is written into out. Note that in and out can be the same array. The length of both in and out must be the block length as returned by blockLength.

Parameters:
in - the plaintext to be encrypted
out - the ciphertext result of the encryption
Throws:
CryptoError - if a buffer was the wrong length

decrypt

public final void decrypt(byte[] in,
                          byte[] out)
Decrypt a block of data. The ciphertext in in is decrypted and the plaintext is written into out. Note that in and out can be the same array. The length of both in and out must be the block length as returned by blockLength.

Parameters:
in - the ciphertext to be decrypted
out - the plaintext result of the encryption
Throws:
CryptoError - if a buffer was the wrong length

encrypt

public final void encrypt(byte[] in,
                          int in_offset,
                          byte[] out,
                          int out_offset)
Encrypt a block of data within an array. The plaintext in in is encrypted from in_offset to (in_offset + blockLength - 1) and the ciphertext is written into out from out_offset to (out_offset + blockLength - 1) Note that there must be at least blockLength bytes left in each array at the supplied offsets.

Parameters:
in - buffer holding the plaintext to be encrypted
in_offset - the start of plaintext within in
out - buffer to hold the encrypted ciphertext result
out_offset - the start of cyphertext within out
Throws:
ArrayIndexOutOfBoundsException - if an offset was invalid.

decrypt

public final void decrypt(byte[] in,
                          int in_offset,
                          byte[] out,
                          int out_offset)
Decrypt a block of data within an array. The cyphertext in in is decrypted from in_offset to (in_offset + blockLength - 1) and the plaintext is written into out from out_offset to (out_offset + blockLength - 1) Note that there must be at least blockLength bytes left in each array at the supplied offsets.

Parameters:
in - buffer holding the cyphertext to be decrypted
in_offset - the start of cyphertext within in
out - buffer to hold the decrypted plaintext result
out_offset - the start of plaintext within out
Throws:
ArrayIndexOutOfBoundsException - if an offset was invalid.

blockEncrypt

protected abstract void blockEncrypt(byte[] in,
                                     int in_offset,
                                     byte[] out,
                                     int out_offset)
Perform an encryption in the extended class. The plaintext in in is encrypted from in_offset to (in_offset + blockLength - 1) and the ciphertext is written into out from out_offset to (out_offset + blockLength - 1) Note that there will be at least blockLength bytes left in each array at the supplied offsets, this is checked in the superclass. The in and out buffers can be the same.

Parameters:
in - buffer holding the plaintext to be encrypted
in_offset - the start of plaintext within in
out - buffer to hold the encrypted ciphertext result
out_offset - the start of cyphertext within out

blockDecrypt

protected abstract void blockDecrypt(byte[] in,
                                     int in_offset,
                                     byte[] out,
                                     int out_offset)
Perform a decryption in the extended class. The cyphertext in in is decrypted from in_offset to (in_offset + blockLength - 1) and the plaintext is written into out from out_offset to (out_offset + blockLength - 1) Note that there will be at least blockLength bytes left in each array at the supplied offsets, this is checked in the superclass. The in and out buffers can be the same.

Parameters:
in - buffer holding the cyphertext to be decrypted
in_offset - the start of cyphertext within in
out - buffer to hold the decrypted plaintext result
out_offset - the start of plaintext within out

blockLength

public abstract int blockLength()
Return the block length of this cipher. Note that for variable block length ciphers, this will return the length of the block as initiated by the constructor. (For variable length ciphers, consider implementing blockLengthMin, blockLengthMax and blockLengthMod).

Returns:
the block length (in bytes) of this object

keyLength

public abstract int keyLength()
Return the key length for this cipher. Note that for variable key length ciphers, this will return the length of the block as initiated by the constructor.

Returns:
the key length (in bytes) of this object