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 */ init(boolean forEncryption, CipherParameters params)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 */ getAlgorithmName()29 public String getAlgorithmName(); 30 31 /** 32 * return the cipher this object wraps. 33 * 34 * @return the cipher this object wraps. 35 */ getUnderlyingCipher()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 */ processByte(byte in, byte[] out, int outOff)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 */ processBytes(byte[] in, int inOff, int len, byte[] out, int outOff)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 */ doFinal(byte[] out, int outOff)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 */ getMac()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 */ getUpdateOutputSize(int len)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 */ getOutputSize(int len)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 */ reset()107 public void reset(); 108 } 109