package gnu.crypto.pad;

// ----------------------------------------------------------------------------
// $Id: IPad.java,v 1.4 2005/10/06 04:24:17 rsdio Exp $
//
// Copyright (C) 2001, 2002, Free Software Foundation, Inc.
//
// This file is part of GNU Crypto.
//
// GNU Crypto is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2, or (at your option)
// any later version.
//
// GNU Crypto is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; see the file COPYING.  If not, write to the
//
//    Free Software Foundation Inc.,
//    51 Franklin Street, Fifth Floor,
//    Boston, MA 02110-1301
//    USA
//
// Linking this library statically or dynamically with other modules is
// making a combined work based on this library.  Thus, the terms and
// conditions of the GNU General Public License cover the whole
// combination.
//
// As a special exception, the copyright holders of this library give
// you permission to link this library with independent modules to
// produce an executable, regardless of the license terms of these
// independent modules, and to copy and distribute the resulting
// executable under terms of your choice, provided that you also meet,
// for each linked independent module, the terms and conditions of the
// license of that module.  An independent module is a module which is
// not derived from or based on this library.  If you modify this
// library, you may extend this exception to your version of the
// library, but you are not obligated to do so.  If you do not wish to
// do so, delete this exception statement from your version.
// ----------------------------------------------------------------------------

/**
 * <p>The basic visible methods of any padding algorithm.</p>
 *
 * <p>Padding algorithms serve to <i>pad</i> and <i>unpad</i> byte arrays usually
 * as the last step in an <i>encryption</i> or respectively a <i>decryption</i>
 * operation. Their input buffers are usually those processed by instances of
 * {@link gnu.crypto.mode.IMode} and/or {@link gnu.crypto.cipher.IBlockCipher}.</p>
 *
 * @version $Revision: 1.4 $
 */
public interface IPad {

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

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

   /** @return the canonical name of this instance. */
   String name();

   /**
    * Initialises the padding scheme with a designated block size.
    *
    * @param bs the designated block size.
    * @exception IllegalStateException if the instance is already initialised.
    * @exception IllegalArgumentException if the block size value is invalid.
    */
   void init(int bs) throws IllegalStateException;

   /**
    * Returns the byte sequence that should be appended to the designated input.
    *
    * @param in the input buffer containing the bytes to pad.
    * @param offset the starting index of meaningful data in <i>in</i>.
    * @param length the number of meaningful bytes in <i>in</i>.
    * @return the possibly 0-byte long sequence to be appended to the designated
    * input.
    */
   byte[] pad(byte[] in, int offset, int length);

   /**
    * Returns the number of bytes to discard from a designated input buffer.
    *
    * @param in the input buffer containing the bytes to unpad.
    * @param offset the starting index of meaningful data in <i>in</i>.
    * @param length the number of meaningful bytes in <i>in</i>.
    * @return the number of bytes to discard, to the left of index position
    * <tt>offset + length</tt> in <i>in</i>. In other words, if the return
    * value of a successful invocation of this method is <tt>result</tt>, then
    * the unpadded byte sequence will be <tt>offset + length - result</tt> bytes
    * in <i>in</i>, starting from index position <tt>offset</tt>.
    * @exception WrongPaddingException if the data is not terminated with the
    * expected padding bytes.
    */
   int unpad(byte[] in, int offset, int length) throws WrongPaddingException;

   /**
    * Resets the scheme instance for re-initialisation and use with other
    * characteristics. This method always succeeds.
    */
   void reset();

   /**
    * A basic symmetric pad/unpad test.
    *
    * @return <tt>true</tt> if the implementation passes a basic symmetric
    * self-test. Returns <tt>false</tt> otherwise.
    */
   boolean selfTest();
}
