Streaming encryption is typically used for encrypting large plaintexts such as large files. * Tink may eventually contain multiple interfaces for streaming encryption depending on the * supported properties. This interface supports a streaming interface for symmetric encryption with * authentication. The underlying encryption modes are selected so that partial plaintext can be * obtained fast by decrypting and authenticating just a part of the ciphertext. * *
Instances of StreamingAead must follow the nOAE definition as proposed in the paper "Online * Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance" by Hoang, Reyhanitabar, Rogaway * and Vizár https://eprint.iacr.org/2015/189.pdf * *
Encryption must be done in one session. There is no possibility to modify an existing * ciphertext or append to it (other than reencrypt the whole file again). One reason for this * restriction is the use of AES-GCM as one cipher to implement this interface. If single segments * are modified then this is equivalent to reusing the same IV twice, but reusing an IV twice leaks * an AES-GCM key. Another reason is that implementations of this interface have no protection * against roll-back attacks: an attacker can always try to restore a previous version of the file * without detection. * *
A channel can be in a blocking mode (i.e. always waits until the requested number of bytes * have been processed) or non-blocking mode (i.e. I/O operation will never block and may transfer * fewer bytes than were requested or possibly no bytes at all). * *
If the channel provided to the streaming encryption is in blocking mode then encryption and * decryption have the same property. That is, encryption always processes all the plaintext passed * in, and waits until complete segments have been written to the ciphertext channel (incomplete * segment, if any, is buffered). Similarly, decryption blocks until sufficiently many bytes have * been read from the ciphertext channel so that all the requested plaintext can be decrypted and * authenticated, or until the end of the plaintext has been reached, or an IOException occurred. * *
If the channel provided to the streaming encryption is in non-blocking mode, then encryption * and decryption are also non-blocking. Since encryption and decryption is done in segments it is * possible that for example a call attempting to read() returns no plaintext at all even if partial * ciphertext was read from the underlying channel. * *
{@code
* StreamingAead s = ...
* java.nio.channels.FileChannel ciphertextDestination =
* new FileOutputStream(ciphertextFile).getChannel();
* byte[] aad = ...
* WritableByteChannel encryptingChannel = s.newEncryptingChannel(ciphertextDestination, aad);
* while ( ... ) {
* int r = encryptingChannel.write(buffer);
* ...
* }
* encryptingChannel.close();
* }
*
* {@code
* StreamingAead s = ...
* java.nio.channels.FileChannel ciphertextSource =
* new FileInputStream(ciphertextFile).getChannel();
* byte[] aad = ...
* ReadableByteChannel decryptingChannel = s.newDecryptingChannel(ciphertextSource, aad);
* int chunkSize = ...
* ByteBuffer buffer = ByteBuffer.allocate(chunkSize);
* do {
* buffer.clear();
* int cnt = decryptingChannel.read(buffer);
* if (cnt > 0) {
* // Process cnt bytes of plaintext.
* } else if (read == -1) {
* // End of plaintext detected.
* break;
* } else if (read == 0) {
* // No ciphertext is available at the moment.
* }
* }
* }
*
* @since 1.1.0
*/
public interface StreamingAead {
/**
* Returns a WritableByteChannel for plaintext. Any data written to the returned
* channel will be encrypted and the resulting ciphertext written to the provided
* {@code ciphertextDestination}
*
* @param ciphertextDestination the channel to which the ciphertext is written.
* @param associatedData data associated with the plaintext. This data is authenticated
* but not encrypted. It must be passed into the decryption.
*/
WritableByteChannel newEncryptingChannel(
WritableByteChannel ciphertextDestination, byte[] associatedData)
throws GeneralSecurityException, IOException;
/**
* Returns a SeekableByteChannel that allows to access the plaintext.
*
* This method does not work on Android Marshmallow (API level 23) or older because these * Android versions don't have the java.nio.channels.SeekableByteChannel interface. * * @param ciphertextSource the ciphertext * @param associatedData the data associated with the ciphertext. * @return {@link SeekableByteChannel} that allows random read access to the plaintext. The * following methods of SeekableByteChannel are implemented: *
Throws {@link IOException} if a MAC verification failed. TODO: Should we extend * the interface with read(ByteBuffer dst, long position) to avoid race conditions? *
The returned InputStream may support {@code mark()}/{@code reset()}, * but does not have to do it -- {@code markSupported()} provides the corresponding info. * *
The returned InputStream supports {@code skip()}, yet possibly in an inefficient way, * i.e. by reading a sequence of blocks until the desired position. If a more efficient * {@code skip()}-functionality is needed, the Channel-based API can be used. */ InputStream newDecryptingStream(InputStream ciphertextSource, byte[] associatedData) throws GeneralSecurityException, IOException; }