/* @(#)MessageDigestSpiTestable.java	3.0	2005-03-01
 * This file was freely contributed to the LimeWire project and is covered
 * by its existing GPL licence, but it may be used individually as a public
 * domain implementation of a published engine (see below for references).
 * It was also freely contributed to the Bitzi public domain sources.
 * @author Philippe Verdy
 */
package org.rodage.pub.tests.security;

import java.security.DigestException;

/**
 * This interface just redeclares the protected methods of the abstract
 * MessageDigestSpi class overriden in the actual SPI implementation,
 * into public concrete methods that must be implemented in a derived
 * delegating class calling the protected implementation to test.
 *   
 * @author Philippe Verdy
 */
interface MessageDigestSpiTestable {
    /**
     * Clones this object.
     * 
     * Implementation overrides the protected abstract method of
     * <code>java.lang.Object</code>.
     * @see java.lang.Object#clone()
     */
    Object clone() throws CloneNotSupportedException;

    /**
     * Reset then initialize the digest context.
     * 
     * @see java.security.MessageDigestSpi#engineReset()
     */
    void engineReset();

    /**
     * Returns the digest length in bytes.
     *
     * Can be used to allocate your own output buffer when
     * computing multiple digests.
     * 
     * @return the digest length in bytes.
     * @see java.security.MessageDigestSpi#engineGetDigestLength()
     */
    int engineGetDigestLength();

    /**
     * Updates the digest using the specified byte.
     * Requires internal buffering, and may be slow.
     * 
     * @param input  the byte to use for the update.
     * @see java.security.MessageDigestSpi#engineUpdate(byte)
     */
    void engineUpdate(byte input);

    /**
     * Updates the digest using the specified array of bytes,
     * starting at the specified offset.
     *
     * Input length can be any size. May require internal buffering,
     * if input block sizes are not multiple of the algorithm's
     * core block processing size.
     * 
     * @param input  the array of bytes to use for the update.
     * @param offset the offset to start from in the array of bytes.
     * @param len    the number of bytes to use, starting at offset.
     * @see java.security.MessageDigestSpi#engineUpdate(byte[], int, int)
     */
    void engineUpdate(byte[] input, int offset, int len);

    /**
     * Completes the hash computation by performing final operations
     * such as padding. Once engineDigest has been called, the engine
     * will be automatically reset (see engineReset).
     * 
     * @param hashvalue  the output buffer in which to store the digest.
     * @param offset  offset to start from in the output buffer.
     * @param len  number of bytes within buf allotted for the digest.
     *             Both this default implementation and the SUN provider
     *             do not return partial digests.  The presence of this
     *             parameter is solely for consistency in our API's.
     *             If the value of this parameter is less than the
     *             actual digest length, the method will throw a
     *             DigestException.  This parameter is ignored if its
     *             value is greater than or equal to the actual digest
     *             length.
     * @return  the length of the digest stored in the output buffer.
     * @see java.security.MessageDigestSpi#engineDigest(byte[], int, int)
     */
    int engineDigest(byte[] hashvalue, int offset, int len)
            throws DigestException;

    /**
     * Completes the hash computation by performing final operations
     * such as padding. Computes the final hash and returns the final
     * value as a byte[24] array. Once engineDigest has been called,
     * the engine will be automatically reset as specified in the
     * JavaSecurity MessageDigest specification.
     *
     * For faster operations with multiple digests, allocate your own
     * array and use engineDigest(byte[], int offset, int len).
     * 
     * @return the length of the digest stored in the output buffer.
     * @see java.security.MessageDigestSpi#engineDigest()
     */
    byte[] engineDigest();
}