Comment on page
Stream and file encryption
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.
Initialises 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(bool decryption, Span<byte> header, ReadOnlySpan<byte> key);
header has a length not equal to HeaderSize.key has a length not equal to KeySize.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.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.secretstream.Push(Span<byte> ciphertextChunk, ReadOnlySpan<byte> plaintextChunk, ReadOnlySpan<byte> associatedData = default, ChunkFlag chunkFlag = ChunkFlag.Message)
ciphertextChunk has a length not equal to plaintextChunk.Length + TagSize.Cannot push into a decryption stream or push after
ChunkFlag.Final.Encryption failed.
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.var chunkFlag = secretstream.Pull(Span<byte> plaintextChunk, ReadOnlySpan<byte> ciphertextChunk, ReadOnlySpan<byte> associatedData = default)
plaintextChunk has a length not equal to ciphertextChunk.Length - TagSize.Cannot pull from an encryption stream or pull after
ChunkFlag.Final.Invalid authentication tag for the given inputs.
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.secretstream.Rekey()
Cannot rekey after
ChunkFlag.Final.These are used for validation and/or save you defining your own constants.
public const int KeySize = 32;
public const int HeaderSize = 24;
public const int TagSize = 17;
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).
As a general rule, avoid compression before encryption. It can leak information and has been the cause of several attacks.
Last modified 2mo ago