//==============================================================================
// Cipher.java
//==============================================================================

package tribble.crypto;


// System imports

import java.lang.Exception;
import java.lang.NullPointerException;
import java.lang.String;
import java.lang.System;
import java.lang.UnsupportedOperationException;

import java.security.AlgorithmParameters;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.Key;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;

import java.security.spec.AlgorithmParameterSpec;

import javax.crypto.BadPaddingException;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.ShortBufferException;


/*******************************************************************************
* Cryptographic cipher implementation.
*
* <p>
* This class generates instances of cryptographic cipher algorithms.
*
* <p>
* Cipher objects (of type <tt>javax.crypto.Cipher</tt>) are constructed from a
* combination of a cipher SPI object, which is one of generic cipher algorithm
* types derived from this class, {@link CipherSpi}, and a primitive cipher
* algorithm, which is a class derived from class {@link AbstractCipher}.
*
* <!-- --------------------------------------------------------------------- -->
* @version	API 2, $Revision: 1.1 $ $Date: 2005/09/11 04:28:52 $
* @since	JCE 1.2 / JRE 1.4, 2005-09-10
* @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	CipherSpi
* @see	AbstractCipher
* @see	MyProvider
*/

public abstract class Cipher
    extends javax.crypto.Cipher
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/crypto/Cipher.java $Revision: 1.1 $ $Date: 2005/09/11 04:28:52 $\n";

    /** Class series version. */
    public static final int	SERIES =	200;


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Constants

    //----------------------------------
    // Cipher initialization modes

    /** Initialization mode: Encryption.
    * (Same as <tt>Cipher.ENCRYPT_MODE</tt>.)
    */
    public static final short	ENCRYPT_MODE =	Cipher.ENCRYPT_MODE;

    /** Initialization mode: Decryption.
    * (Same as <tt>Cipher.DECRYPT_MODE</tt>.)
    */
    public static final short	DECRYPT_MODE =	Cipher.DECRYPT_MODE;


    //----------------------------------
    // Cipher key types

    /** Key type: Secret.
    * (Same as <tt>Cipher.SECRET_KEY</tt>.)
    */
    public static final short	SECRET_KEY =	Cipher.SECRET_KEY;

    /** Key type: Public.
    * (Same as <tt>Cipher.PUBLIC_KEY</tt>.)
    */
    public static final short	PUBLIC_KEY =	Cipher.PUBLIC_KEY;

    /** Key type: Private.
    * (Same as <tt>Cipher.PRIVATE_KEY</tt>.)
    */
    public static final short	PRIVATE_KEY =	Cipher.PRIVATE_KEY;


    //----------------------------------
    // Cipher key wrapping modes

    /** Key wrap mode: Wrap.
    * (Same as <tt>Cipher.WRAP_MODE</tt>.)
    */
    public static final short	WRAP_MODE =	Cipher.WRAP_MODE;

    /** Key wrap mode: Unwrap.
    * (Same as <tt>Cipher.UNWRAP_MODE</tt>.)
    */
    public static final short	UNWRAP_MODE =	Cipher.UNWRAP_MODE;


///+Duplicates in CipherSpi
    //----------------------------------
    // Operating mode types

    /** Operating mode (block): ECB, electronic codebook (no chaining). */
    public static final String	MODE_ECB =	"ECB";

    /** Operating mode (block): CBC, cipher block chaining. */
    public static final String	MODE_CBC =	"CBC";

    /** Operating mode (block): PBC, plaintext block chaining. */
    public static final String	MODE_PBC =	"PBC";

    /** Operating mode (block): PCBC, propagating cipher block chaining. */
    public static final String	MODE_PCBC =	"PCBC";

    /** Operating mode (block): BC, block chaining. */
    public static final String	MODE_BC =	"BC";

    /** Operating mode (stream): CFB, cipher feedback. */
    public static final String	MODE_CFB =	"CFB";

    /** Operating mode (stream): CFB-8, cipher feedback. */
    public static final String	MODE_CFB8 =	"CFB8";

    /** Operating mode (stream): OFB, output feedback. */
    public static final String	MODE_OFB =	"OFB";

    /** Operating mode (stream): OFB-8, output feedback. */
    public static final String	MODE_OFB8 =	"OFB8";

    /** Operating mode (stream): PFB, plaintext feedback. */
    public static final String	MODE_PFB =	"PFB";

    /** Operating mode (stream): PFB-8, plaintext feedback. */
    public static final String	MODE_PFB8 =	"PFB8";

    /** Operating mode (stream): CTR, counter mode. */
    public static final String	MODE_CTR =	"CTR";

    /** Operating mode (stream): CTR-8, counter mode. */
    public static final String	MODE_CTR8 =	"CTR8";


///+Duplicates in CipherSpi
    //----------------------------------
    // Padding scheme types

    /** Padding scheme: None. */
    public static final String	PADDING_NONE =	"NoPadding";

    /** Padding scheme: PKCS#5. */
    public static final String	PADDING_PKCS5 =	"PKCS5Padding";

    /** Padding scheme: Pad with zero bytes (nulls). */
    public static final String	PADDING_ZEROS =	"NullPadding";

    /** Padding scheme: Ciphertext stealing in the final partial block. */
    public static final String	PADDING_CTS =	"CiphertextStealing";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Static methods

    /***************************************************************************
    * Generates a {@link Cipher} object that implements the specified
    * transformation.
    *
    * <p>
    * This method corresponds to the <tt>getInstance()</tt> method of class
    * <tt>javax.crypto.Cipher</tt>.
    *
    * @param	trans
    * The name of the transformation, e.g., <tt>"AES/CBC/PKCS5Padding"</tt>.
    *
    * @return
    * A cipher that implements the requested transformation.
    *
    * @throws	NoSuchAlgorithmException
    * Thrown if <tt>trans</tt> does not specify a transformation provided by
    * this implementation package.
    *
    * @throws	 NoSuchPaddingException
    * Thrown if <tt>trans</tt> does not specify a padding scheme provided by
    * this implementation package.
    *
    * @since	1.1, 2005-09-10
    */

    public static final Cipher getCipher(String trans)
        throws NoSuchAlgorithmException, NoSuchPaddingException
    {
        return (MyProvider.getInstance(trans));
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Variables

    /** Cryptographic SPI implementation object. */
    private CipherSpi		m_spi;


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Constructors

    /***************************************************************************
    * Constructor.
    *
    * @param	spi
    * Cryptographic SPI delegate.
    *
    * @param	trans
    * Cryptographic transform name.
    * This is composed of the algorithm name, the mode type, and the padding
    * scheme.
    *
    * @throws	NoSuchAlgorithmException
    * Thrown if <tt>trans</tt> does not specify a supported operating mode.
    *
    * @throws	NoSuchPaddingException
    * Thrown if <tt>trans</tt> does not specify a supported padding scheme.
    *
    * @since	1.1, 2005-09-10
    */

    Cipher(CipherSpi spi, String trans)
        throws NoSuchAlgorithmException, NoSuchPaddingException
    {
        // Initialize
        super(spi, MyProvider.PROVIDER, trans);
        m_spi = spi;
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Methods

    /***************************************************************************
    * Clear (wipe) this cipher.
    * Erases all sensitive information contained within this object.
    *
    * <p>
    * This method is not part of the standard set defined in class
    * <tt>javax.crypto.Cipher</tt>, but is provided as a convenient
    * enhancement.
    *
    * <p>
    * Note that this cipher object is no longer usable after calling this
    * method.
    *
    * @since	1.1, 2005-09-10
    */

    public void clear()
    {
        // Wipe sensitive data
        if (m_spi != null)
        {
            m_spi.engineClear();
            m_spi = null;
        }
    }


    /***************************************************************************
    * Finalization.
    * Erases all sensitive information contained within this object prior to it
    * being garbage-collected.
    *
    * @since	1.1, 2005-09-10
    */

    protected synchronized void finalize()
        throws Throwable
        //overrides javax.crypto.Cipher
    {
        // Wipe the contents of this object
        clear();

        // Cascade the finalization
        super.finalize();
    }
}

// End Cipher.java