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