An interface for streaming authenticated encryption with associated data.
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.
Security guarantees
Instances of StreamingAead must follow the OAE2 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
Restrictions
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.
Blocking vs non-blocking I/O
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.
Sample encryption
StreamingAead s = ...encryptingChannel.close();
}
Sample full decryption
StreamingAead s = ...else if (read == -1)
// End of plaintext detected.
break;
} else if (read == 0)
// No ciphertext is available at the moment.
}
}
}