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); ** * In general, method
* 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" ); *
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. * *
*
* @author Systemics Ltd
* @see StreamCipher
* @see SPEED
* @see IDEA
*/
public abstract class BlockCipher
{
/**
* 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.
*
* @param text the buffer holding the data
*/
public final void
encrypt( byte text[] )
{
encrypt( text, 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.
*
* @param text the buffer holding the data
*/
public final void
decrypt( byte text[] )
{
decrypt( text, text );
}
/**
* 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.
*
* @param in the plaintext to be encrypted
* @param out the ciphertext result of the encryption
* @exception CryptoError if a buffer was the wrong length
*/
public final void
encrypt( byte in[], byte out[] )
{
int len = blockLength();
if ( (in.length != len) || (out.length != len) )
throw new CryptoError( getClass().getName() +
": encrypt buffers must be the same size as cipher length" );
encrypt( in, 0, out, 0 );
}
/**
* 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.
*
* @param in the ciphertext to be decrypted
* @param out the plaintext result of the encryption
* @exception CryptoError if a buffer was the wrong length
*/
public final void
decrypt( byte in[], byte out[] )
{
int len = blockLength();
if ( (in.length != len) || (out.length != len) )
throw new CryptoError( getClass().getName() +
": decrypt buffers must be the same size as cipher length" );
decrypt( in, 0, out, 0 );
}
/**
* 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.
*
* @param in buffer holding the plaintext to be encrypted
* @param in_offset the start of plaintext within in
* @param out buffer to hold the encrypted ciphertext result
* @param out_offset the start of cyphertext within out
* @exception ArrayIndexOutOfBoundsException if an offset was invalid.
*/
public final void
encrypt( byte in[], int in_offset, byte out[], int out_offset )
{
int blkLength = blockLength();
if ( in_offset < 0 || out_offset < 0 )
{
throw new ArrayIndexOutOfBoundsException(
getClass().getName() +
": Negative offset not allowed" );
}
if ( ( in_offset + blkLength ) > in.length ||
( out_offset + blkLength ) > out.length )
{
throw new ArrayIndexOutOfBoundsException(
getClass().getName() +
": Offset past end of array" );
}
//
// This is wrong, I think. Now in other methods. Iang.
// if ( ( in.length != blkLength ) ||
// ( out.length != blkLength ) )
// throw new CryptoError( getClass().getName() +
// ": encrypt length must be " + blkLength );
blockEncrypt( in, in_offset, out, 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.
*
* @param in buffer holding the cyphertext to be decrypted
* @param in_offset the start of cyphertext within in
* @param out buffer to hold the decrypted plaintext result
* @param out_offset the start of plaintext within out
* @exception ArrayIndexOutOfBoundsException if an offset was invalid.
*/
public final void
decrypt( byte in[], int in_offset, byte out[], int out_offset )
{
int blkLength = blockLength();
if ( in_offset < 0 || out_offset < 0 )
{
throw new ArrayIndexOutOfBoundsException(
getClass().getName() +
": Negative offset not allowed" );
}
if ( ( in_offset + blkLength ) > in.length ||
( out_offset + blkLength ) > out.length )
{
throw new ArrayIndexOutOfBoundsException(
getClass().getName() +
": Offset past end of array" );
}
// if ( ( in.length != blkLength ) ||
// ( out.length != blkLength ) )
// throw new CryptoError( getClass().getName() +
// ": decrypt length must be " + blkLength );
blockDecrypt( in, in_offset, out, 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.
*
*
* @param in buffer holding the plaintext to be encrypted
* @param in_offset the start of plaintext within in
* @param out buffer to hold the encrypted ciphertext result
* @param out_offset the start of cyphertext within out
*/
protected abstract void
blockEncrypt(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.
*
* @param in buffer holding the cyphertext to be decrypted
* @param in_offset the start of cyphertext within in
* @param out buffer to hold the decrypted plaintext result
* @param out_offset the start of plaintext within out
*/
protected abstract void
blockDecrypt(byte in[], int in_offset, byte out[], int out_offset );
//
// This comment was here originally, but I don't think
// it is appropriate because of variable key algorithms. iang.
// N.B. the library writer should also implement a
// public static final int BLOCK_LENGTH
// for any classes that derive from this one.
//
/**
* 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).
*
* @return the block length (in bytes) of this object */ public abstract int blockLength(); /** * 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. *
* @return the key length (in bytes) of this object */ public abstract int keyLength(); }