Stream and file encryption
Purpose
Encrypting streams and files should be done in chunks. This keeps memory usage low and detects corrupted chunks early. However, this is more complicated than one would expect because you need to prevent chunks from being removed, truncated, duplicated, and reordered.
This high-level API uses XChaCha20-Poly1305 internally whilst handling these issues for you. Plaintext chunks can have different sizes, there is no practical stream length limit, associated data is supported, and rekeying is possible midway through encrypting the stream.
The optional associated data is useful for authenticating file headers, version numbers, timestamps, counters, and so on. It can be used to prevent confused deputy attacks and replay attacks. It is not encrypted nor part of the ciphertext. It must be reproduceable or stored somewhere for decryption to be possible.
For file encryption, optimal chunk sizes include 16 KiB, 32 KiB, and 64 KiB. Pick one and use it for everything but the last chunk, which will likely be smaller.
Usage
IncrementalXChaCha20Poly1305
Initializes stream encryption or decryption using a key and header. For encryption, the header is filled with a random nonce. It MUST be sent/stored before the sequence of ciphertext messages because it is required to decrypt the stream.
using var secretstream = new IncrementalXChaCha20Poly1305(Span<byte> header, ReadOnlySpan<byte> key, bool encryption)Exceptions
header has a length not equal to HeaderSize.
key has a length not equal to KeySize.
Methods cannot be called from multiple threads simultaneously.
Allocating memory for the state failed.
Error initializing stream encryption/decryption.
ChunkFlag
Before encryption, a flag is attached to each chunk to provide information about that chunk:
ChunkFlag.Message: an ordinary plaintext chunk.ChunkFlag.Boundary: the end of a set of messages but not the end of the stream.ChunkFlag.Rekey: derive a new key after this chunk.ChunkFlag.Final: the last plaintext chunk, marking the end of the stream.
For file encryption, ChunkFlag.Message and ChunkFlag.Final are the only flags required. For online communication, ChunkFlag.Boundary and ChunkFlag.Rekey may also be useful.
During decryption, you MUST check that the last chunk had the ChunkFlag.Final flag. Otherwise, you MUST throw a CryptographicException to detect stream truncation.
EncryptChunk
Fills a span with the ciphertext chunk computed from a plaintext chunk and optional associated data. ChunkFlag.Final MUST be specified for the last plaintext chunk.
Exceptions
ciphertextChunk has a length not equal to plaintextChunk.Length + TagSize.
chunkFlag must be a value within the enum.
Cannot encrypt on a decryption stream or after the final chunk without reinitializing.
Methods cannot be called from multiple threads simultaneously.
The object has been disposed.
Error encrypting plaintext chunk.
DecryptChunk
Verifies that the tag appended to the ciphertext chunk is correct for the given inputs. If verification fails, an exception is thrown. Otherwise, it fills a span with the decrypted ciphertext and returns the decrypted flag for that chunk.
To detect stream truncation, if you reach the end of the stream and ChunkFlag.Final was not returned, you MUST throw a CryptographicException.
Exceptions
ciphertextChunk has a length less than TagSize.
plaintextChunk has a length not equal to ciphertextChunk.Length - TagSize.
Cannot decrypt on an encryption stream or after the final chunk without reinitializing.
Methods cannot be called from multiple threads simultaneously.
The object has been disposed.
Invalid chunk authentication tag for the given inputs.
Rekey
Explicitly rekeys without storing the ChunkFlag.Rekey flag. For decryption, this function MUST be called at the same stream location to avoid an exception when decrypting the following chunk.
Exceptions
Cannot rekey after the final chunk without reinitializing.
Methods cannot be called from multiple threads simultaneously.
The object has been disposed.
Reinitialize
Reinitializes stream encryption or decryption using a key and header. This avoids creating another using statement. For encryption, the header is filled with a random nonce. It MUST be sent/stored before the sequence of ciphertext messages because it is required to decrypt the stream.
Exceptions
header has a length not equal to HeaderSize.
key has a length not equal to KeySize.
Methods cannot be called from multiple threads simultaneously.
The object has been disposed.
Allocating memory for the state failed.
Error initializing stream encryption/decryption.
Constants
These are used for validation and/or save you defining your own constants.
Notes
If you intend to feed multiple variable-length inputs into the associated data, beware of canonicalization attacks. Please read the Concat page for more information.
The key MUST be uniformly random. It can either be randomly generated or the output of a KDF. Furthermore, it SHOULD be rotated periodically (e.g., a different key per file).
Do NOT use this class with multiple threads. If you absolutely have to, you need to use lock statements to avoid exceptions being thrown.
As a general rule, avoid compression before encryption. It can leak information and has been the cause of several attacks.
Last updated