//==============================================================================
// AbstractCipher.java
//==============================================================================

package tribble.crypto;


// System imports

import java.lang.Exception;
import java.lang.String;
import java.lang.System;
import java.lang.Throwable;

import java.security.InvalidKeyException;
import java.security.Key;


// Local imports

// (None)


/*******************************************************************************
* Abstract base class for fundamental cipher (encryption) algorithms.
*
* <p>
* Cipher objects (of type <tt>javax.crypto.Cipher</tt>) are constructed from
* provider-specific implementations of Cipher SPIs (of type
* <tt>javax.crypto.CipherSpi</tt>).
* This package, in turn, constructs Cipher SPI objects from a combination of a
* cipher SPI object, which is one of three generic cipher algorithm types
* ({@link SymmetricCipherSpi}, {@link AsymmetricCipherSpi}, or
* {@link StreamCipherSpi}), and a primitive cipher algorithm object,
* which is a class derived from either
* {@link SymmetricCipher} or {@link AsymmetricCipher}.
*
* <p>
* The {@link SymmetricCipher} and {@link AsymmetricCipher} types implement the
* primitive encryption cipher algorithms that serve as the foundation upon which
* the rest of this cryptographic package is built.  These two classes, in other
* words, are the fundamental encryption algorithms for this entire package.
*
* <!-- --------------------------------------------------------------------- -->
* @version	$Revision: 1.2 $ $Date: 2005/07/09 14:39:22 $
* @since	2005-07-05
* @author
*	David R. Tribble
*	(<a href="mailto:david@tribble.com">david@tribble.com</a>).
*
*	<p>
*	Copyright ©2005 by David R. Tribble, all rights reserved.
*	<br>
*	Permission is granted to freely use and distribute this source code
*	provided that the original copyright and authorship notices remain
*	intact.
*
* @see	AsymmetricCipher
* @see	SymmetricCipher
* @see	CipherSpi
* @see	AsymmetricCipherSpi
* @see	SymmetricCipherSpi
* @see	StreamCipherSpi
*/

public abstract class AbstractCipher
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/crypto/AbstractCipher.java $Revision: 1.2 $ $Date: 2005/07/09 14:39:22 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected variables

    /** Cipher algorithm name. */
    protected String		m_alg;

    /** Key size (in bytes). */
    protected int		m_keyLen;

    /** Cipher is in decryption, not encryption, mode. */
    protected boolean		m_decrypt;

    /** Cipher has been initialized. */
    protected boolean		m_init;


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods

    /***************************************************************************
    * Retrieve the algorithm name of this cipher.
    *
    * @return
    * Cryptographic cipher algorithm name.
    *
    * @since	1.2, 2005-07-08
    */

    public String getAlgorithm()
        /*const*/
    {
        return (m_alg);
    }


    /***************************************************************************
    * Retrieve the key size of this cipher.
    *
    * @return
    * The key size of this cipher algorithm (in bytes).
    *
    * @since	1.2, 2005-07-08
    */

    public int getKeySize()
        /*const*/
    {
        return (m_keyLen);
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected constructors

    /***************************************************************************
    * Constructor.
    *
    * @param	alg
    * Cryptographic cipher algorithm name.
    *
    * @since	1.1, 2005-07-05
    */

    protected AbstractCipher(String alg)
    {
        // Initialize
        m_alg = alg;
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected methods

    /***************************************************************************
    * Initialize this cipher.
    *
    * <!-- ----------------------------- -->
    * @param	key
    * The encryption key for this cipher.
    *
    * @param	decrypt
    * If true, this indicates that this cipher is to be initialized for
    * decrypting, otherwise it is to be initialized for encrypting.
    *
    * @see	#clear clear()
    *
    * @since	1.1, 2005-07-05
    */

    protected abstract void initialize(byte[] key, boolean decrypt)
        throws InvalidKeyException;


    /***************************************************************************
    * Reset this cipher, wiping all sensitive information.
    *
    * <p>
    * This method will be called after this cipher object is no longer needed.
    * It should overwrite any sensitive data contained within this object
    * (e.g., encryption key schedules).
    * This cipher object can no longer be used after this method has been
    * called.
    *
    * <!-- ----------------------------- -->
    * @see	#initialize initialize()
    *
    * @since	1.1, 2005-07-05
    */

    protected abstract void clear();


    /***************************************************************************
    * Finalization.
    * This resets this cipher object (by calling {@link #clear clear()},
    * wiping all sensitive information prior to this object being
    * garbage-collected.
    *
    * <!-- ----------------------------- -->
    * @see	#clear clear()
    *
    * @since	1.1, 2005-07-05
    */

    protected synchronized void finalize()
        throws Throwable
    {
        // Wipe sensitive info
        clear();

        // Cascade
        super.finalize();
    }
}

// End AbstractCipher.java