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  * <p>
     11  * Implementations of this interface may operate in a packet mode (where all input data is buffered and
     12  * processed dugin the call to {@link #doFinal(byte[], int)}), or in a streaming mode (where output data is
     13  * incrementally produced with each call to {@link #processByte(byte, byte[], int)} or
     14  * {@link #processBytes(byte[], int, int, byte[], int)}.
     15  * </p>
     16  * This is important to consider during decryption: in a streaming mode, unauthenticated plaintext data
     17  * may be output prior to the call to {@link #doFinal(byte[], int)} that results in an authentication
     18  * failure. The higher level protocol utilising this cipher must ensure the plaintext data is handled
     19  * appropriately until the end of data is reached and the entire ciphertext is authenticated.
     20  * @see org.bouncycastle.crypto.params.AEADParameters
     21  */
     22 public interface AEADBlockCipher
     23 {
     24     /**
     25      * initialise the underlying cipher. Parameter can either be an AEADParameters or a ParametersWithIV object.
     26      *
     27      * @param forEncryption true if we are setting up for encryption, false otherwise.
     28      * @param params the necessary parameters for the underlying cipher to be initialised.
     29      * @exception IllegalArgumentException if the params argument is inappropriate.
     30      */
     31     public void init(boolean forEncryption, CipherParameters params)
     32         throws IllegalArgumentException;
     33 
     34     /**
     35      * Return the name of the algorithm.
     36      *
     37      * @return the algorithm name.
     38      */
     39     public String getAlgorithmName();
     40 
     41     /**
     42      * return the cipher this object wraps.
     43      *
     44      * @return the cipher this object wraps.
     45      */
     46     public BlockCipher getUnderlyingCipher();
     47 
     48     /**
     49      * Add a single byte to the associated data check.
     50      * <br>If the implementation supports it, this will be an online operation and will not retain the associated data.
     51      *
     52      * @param in the byte to be processed.
     53      */
     54     public void processAADByte(byte in);
     55 
     56     /**
     57      * Add a sequence of bytes to the associated data check.
     58      * <br>If the implementation supports it, this will be an online operation and will not retain the associated data.
     59      *
     60      * @param in the input byte array.
     61      * @param inOff the offset into the in array where the data to be processed starts.
     62      * @param len the number of bytes to be processed.
     63      */
     64     public void processAADBytes(byte[] in, int inOff, int len);
     65 
     66     /**
     67      * encrypt/decrypt a single byte.
     68      *
     69      * @param in the byte to be processed.
     70      * @param out the output buffer the processed byte goes into.
     71      * @param outOff the offset into the output byte array the processed data starts at.
     72      * @return the number of bytes written to out.
     73      * @exception DataLengthException if the output buffer is too small.
     74      */
     75     public int processByte(byte in, byte[] out, int outOff)
     76         throws DataLengthException;
     77 
     78     /**
     79      * process a block of bytes from in putting the result into out.
     80      *
     81      * @param in the input byte array.
     82      * @param inOff the offset into the in array where the data to be processed starts.
     83      * @param len the number of bytes to be processed.
     84      * @param out the output buffer the processed bytes go into.
     85      * @param outOff the offset into the output byte array the processed data starts at.
     86      * @return the number of bytes written to out.
     87      * @exception DataLengthException if the output buffer is too small.
     88      */
     89     public int processBytes(byte[] in, int inOff, int len, byte[] out, int outOff)
     90         throws DataLengthException;
     91 
     92     /**
     93      * Finish the operation either appending or verifying the MAC at the end of the data.
     94      *
     95      * @param out space for any resulting output data.
     96      * @param outOff offset into out to start copying the data at.
     97      * @return number of bytes written into out.
     98      * @throws IllegalStateException if the cipher is in an inappropriate state.
     99      * @throws org.bouncycastle.crypto.InvalidCipherTextException if the MAC fails to match.
    100      */
    101     public int doFinal(byte[] out, int outOff)
    102         throws IllegalStateException, InvalidCipherTextException;
    103 
    104     /**
    105      * Return the value of the MAC associated with the last stream processed.
    106      *
    107      * @return MAC for plaintext data.
    108      */
    109     public byte[] getMac();
    110 
    111     /**
    112      * return the size of the output buffer required for a processBytes
    113      * an input of len bytes.
    114      * <p>
    115      * The returned size may be dependent on the initialisation of this cipher
    116      * and may not be accurate once subsequent input data is processed - this method
    117      * should be invoked immediately prior to input data being processed.
    118      * </p>
    119      *
    120      * @param len the length of the input.
    121      * @return the space required to accommodate a call to processBytes
    122      * with len bytes of input.
    123      */
    124     public int getUpdateOutputSize(int len);
    125 
    126     /**
    127      * return the size of the output buffer required for a processBytes plus a
    128      * doFinal with an input of len bytes.
    129      * <p>
    130      * The returned size may be dependent on the initialisation of this cipher
    131      * and may not be accurate once subsequent input data is processed - this method
    132      * should be invoked immediately prior to a call to final processing of input data
    133      * and a call to {@link #doFinal(byte[], int)}.
    134      * </p>
    135      * @param len the length of the input.
    136      * @return the space required to accommodate a call to processBytes and doFinal
    137      * with len bytes of input.
    138      */
    139     public int getOutputSize(int len);
    140 
    141     /**
    142      * Reset the cipher. After resetting the cipher is in the same state
    143      * as it was after the last init (if there was one).
    144      */
    145     public void reset();
    146 }
    147