Home | History | Annotate | Download | only in modes 
      1 package org.bouncycastle.crypto.modes;
      2 
      3 import org.bouncycastle.crypto.BlockCipher;
      4 import org.bouncycastle.crypto.CipherParameters;
      5 import org.bouncycastle.crypto.DataLengthException;
      6 import org.bouncycastle.crypto.InvalidCipherTextException;
      7 
      8 /**
      9  * A block cipher mode that includes authenticated encryption with a streaming mode and optional associated data.
     10  * @see org.bouncycastle.crypto.params.AEADParameters
     11  */
     12 public interface AEADBlockCipher
     13 {
     14     /**
     15      * initialise the underlying cipher. Parameter can either be an AEADParameters or a ParametersWithIV object.
     16      *
     17      * @param forEncryption true if we are setting up for encryption, false otherwise.
     18      * @param params the necessary parameters for the underlying cipher to be initialised.
     19      * @exception IllegalArgumentException if the params argument is inappropriate.
     20      */
     21     public void init(boolean forEncryption, CipherParameters params)
     22         throws IllegalArgumentException;
     23 
     24     /**
     25      * Return the name of the algorithm.
     26      *
     27      * @return the algorithm name.
     28      */
     29     public String getAlgorithmName();
     30 
     31     /**
     32      * return the cipher this object wraps.
     33      *
     34      * @return the cipher this object wraps.
     35      */
     36     public BlockCipher getUnderlyingCipher();
     37 
     38     /**
     39      * encrypt/decrypt a single byte.
     40      *
     41      * @param in the byte to be processed.
     42      * @param out the output buffer the processed byte goes into.
     43      * @param outOff the offset into the output byte array the processed data starts at.
     44      * @return the number of bytes written to out.
     45      * @exception DataLengthException if the output buffer is too small.
     46      */
     47     public int processByte(byte in, byte[] out, int outOff)
     48         throws DataLengthException;
     49 
     50     /**
     51      * process a block of bytes from in putting the result into out.
     52      *
     53      * @param in the input byte array.
     54      * @param inOff the offset into the in array where the data to be processed starts.
     55      * @param len the number of bytes to be processed.
     56      * @param out the output buffer the processed bytes go into.
     57      * @param outOff the offset into the output byte array the processed data starts at.
     58      * @return the number of bytes written to out.
     59      * @exception DataLengthException if the output buffer is too small.
     60      */
     61     public int processBytes(byte[] in, int inOff, int len, byte[] out, int outOff)
     62         throws DataLengthException;
     63 
     64     /**
     65      * Finish the operation either appending or verifying the MAC at the end of the data.
     66      *
     67      * @param out space for any resulting output data.
     68      * @param outOff offset into out to start copying the data at.
     69      * @return number of bytes written into out.
     70      * @throws IllegalStateException if the cipher is in an inappropriate state.
     71      * @throws org.bouncycastle.crypto.InvalidCipherTextException if the MAC fails to match.
     72      */
     73     public int doFinal(byte[] out, int outOff)
     74         throws IllegalStateException, InvalidCipherTextException;
     75 
     76     /**
     77      * Return the value of the MAC associated with the last stream processed.
     78      *
     79      * @return MAC for plaintext data.
     80      */
     81     public byte[] getMac();
     82 
     83     /**
     84      * return the size of the output buffer required for a processBytes
     85      * an input of len bytes.
     86      *
     87      * @param len the length of the input.
     88      * @return the space required to accommodate a call to processBytes
     89      * with len bytes of input.
     90      */
     91     public int getUpdateOutputSize(int len);
     92 
     93     /**
     94      * return the size of the output buffer required for a processBytes plus a
     95      * doFinal with an input of len bytes.
     96      *
     97      * @param len the length of the input.
     98      * @return the space required to accommodate a call to processBytes and doFinal
     99      * with len bytes of input.
    100      */
    101     public int getOutputSize(int len);
    102 
    103     /**
    104      * Reset the cipher. After resetting the cipher is in the same state
    105      * as it was after the last init (if there was one).
    106      */
    107     public void reset();
    108 }
    109