AEADBlockCipher.java revision e1142c149e244797ce73b0e7fad40816e447a817
1package org.bouncycastle.crypto.modes; 2 3import org.bouncycastle.crypto.BlockCipher; 4import org.bouncycastle.crypto.CipherParameters; 5import org.bouncycastle.crypto.DataLengthException; 6import 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 */ 12public 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 * Add a single byte to the associated data check. 40 * <br>If the implementation supports it, this will be an online operation and will not retain the associated data. 41 * 42 * @param in the byte to be processed. 43 */ 44 public void processAADByte(byte in); 45 46 /** 47 * Add a sequence of bytes to the associated data check. 48 * <br>If the implementation supports it, this will be an online operation and will not retain the associated data. 49 * 50 * @param in the input byte array. 51 * @param inOff the offset into the in array where the data to be processed starts. 52 * @param len the number of bytes to be processed. 53 */ 54 public void processAADBytes(byte[] in, int inOff, int len); 55 56 /** 57 * encrypt/decrypt a single byte. 58 * 59 * @param in the byte to be processed. 60 * @param out the output buffer the processed byte goes into. 61 * @param outOff the offset into the output byte array the processed data starts at. 62 * @return the number of bytes written to out. 63 * @exception DataLengthException if the output buffer is too small. 64 */ 65 public int processByte(byte in, byte[] out, int outOff) 66 throws DataLengthException; 67 68 /** 69 * process a block of bytes from in putting the result into out. 70 * 71 * @param in the input byte array. 72 * @param inOff the offset into the in array where the data to be processed starts. 73 * @param len the number of bytes to be processed. 74 * @param out the output buffer the processed bytes go into. 75 * @param outOff the offset into the output byte array the processed data starts at. 76 * @return the number of bytes written to out. 77 * @exception DataLengthException if the output buffer is too small. 78 */ 79 public int processBytes(byte[] in, int inOff, int len, byte[] out, int outOff) 80 throws DataLengthException; 81 82 /** 83 * Finish the operation either appending or verifying the MAC at the end of the data. 84 * 85 * @param out space for any resulting output data. 86 * @param outOff offset into out to start copying the data at. 87 * @return number of bytes written into out. 88 * @throws IllegalStateException if the cipher is in an inappropriate state. 89 * @throws org.bouncycastle.crypto.InvalidCipherTextException if the MAC fails to match. 90 */ 91 public int doFinal(byte[] out, int outOff) 92 throws IllegalStateException, InvalidCipherTextException; 93 94 /** 95 * Return the value of the MAC associated with the last stream processed. 96 * 97 * @return MAC for plaintext data. 98 */ 99 public byte[] getMac(); 100 101 /** 102 * return the size of the output buffer required for a processBytes 103 * an input of len bytes. 104 * 105 * @param len the length of the input. 106 * @return the space required to accommodate a call to processBytes 107 * with len bytes of input. 108 */ 109 public int getUpdateOutputSize(int len); 110 111 /** 112 * return the size of the output buffer required for a processBytes plus a 113 * doFinal with an input of len bytes. 114 * 115 * @param len the length of the input. 116 * @return the space required to accommodate a call to processBytes and doFinal 117 * with len bytes of input. 118 */ 119 public int getOutputSize(int len); 120 121 /** 122 * Reset the cipher. After resetting the cipher is in the same state 123 * as it was after the last init (if there was one). 124 */ 125 public void reset(); 126} 127