diff options
| author | Jakob Unterwurzacher | 2025-06-03 16:04:11 +0200 |
|---|---|---|
| committer | Jakob Unterwurzacher | 2025-06-03 16:04:11 +0200 |
| commit | 16ed08caf78951bf6bb92945c3e729bb06111f6f (patch) | |
| tree | 42f934715952d8c9615e5a9dbf5bf49f7de1e77e | |
| parent | fb4f2deb5116075a8a38c048cd5e67b554620181 (diff) | |
Documentation: make file-format.md more structured
Also mention that empty files are stored empty.
| -rw-r--r-- | Documentation/file-format.md | 53 |
1 files changed, 41 insertions, 12 deletions
diff --git a/Documentation/file-format.md b/Documentation/file-format.md index 7cce72c..7c2e2c8 100644 --- a/Documentation/file-format.md +++ b/Documentation/file-format.md @@ -1,43 +1,67 @@ File Format =========== +Empty files are stored as empty files. + +Non-empty files contain a *Header* and one or more *Data blocks*. + Header +------ 2 bytes header version (big endian uint16, currently 2) 16 bytes file id Data block, default AES-GCM mode +-------------------------------- 16 bytes GCM IV (nonce) 1-4096 bytes encrypted data 16 bytes GHASH -Data block, AES-SIV mode (used in reverse mode, or when explicitly enabled with `-init -aessiv`) +Overhead = (16+16)/4096 = 1/128 = 0.78125 % + +Data block, AES-SIV mode +------------------------ + +AES-SIV is used in reverse mode, or when explicitly enabled with `-init -aessiv`. 16 bytes nonce 16 bytes SIV 1-4096 bytes encrypted data -Data block, XChaCha20-Poly1305 (enabled via `-init -xchacha`) +Overhead = (16+16)/4096 = 1/128 = 0.78125 % + +Data block, XChaCha20-Poly1305 +------------------------------ + +Enabled via `-init -xchacha` 24 bytes nonce 1-4096 bytes encrypted data 16 bytes Poly1305 tag -Full block overhead (AES-GCM and AES-SIV mode) = 32/4096 = 1/128 = 0.78125 % +Overhead = (24+16)/4096 = 0.98 % -Full block overhead (XChaCha20-Poly1305 mode) = 40/4096 = \~1 % +Examples +======== -Example: 1-byte file, AES-GCM and AES-SIV mode ----------------------------------------------- +0-byte file (all modes) +----------------------- + + (empty) + +Total: 0 bytes + +1-byte file, AES-GCM and AES-SIV mode +------------------------------------- Header 18 bytes Data block 33 bytes Total: 51 bytes -Example: 5000-byte file, , AES-GCM and AES-SIV mode ---------------------------------------------------- +5000-byte file, , AES-GCM and AES-SIV mode +------------------------------------------ Header 18 bytes Data block 4128 bytes @@ -45,19 +69,24 @@ Example: 5000-byte file, , AES-GCM and AES-SIV mode Total: 5082 bytes -Example: 1-byte file, XChaCha20-Poly1305 mode ----------------------------------------------- +1-byte file, XChaCha20-Poly1305 mode +------------------------------------ Header 18 bytes Data block 41 bytes Total: 59 bytes -Example: 5000-byte file, XChaCha20-Poly1305 mode ----------------------------------------------- +5000-byte file, XChaCha20-Poly1305 mode +--------------------------------------- Header 18 bytes Data block 4136 bytes Data block 944 bytes Total: 5098 bytes + +See Also +======== + +https://nuetzlich.net/gocryptfs/forward_mode_crypto/ / https://github.com/rfjakob/gocryptfs-website/blob/master/docs/forward_mode_crypto.md |