From 3b8a0a816a8306bb51217c018cc01de0c71ccb62 Mon Sep 17 00:00:00 2001
From: Alexey Avramov <hakavlad@gmail.com>
Date: Wed, 5 Jun 2024 00:28:02 +0900
Subject: [PATCH] Update Specification

---
 docs/SPECIFICATION.md | 61 +++++++++++++++++++++++++++++++------------
 1 file changed, 45 insertions(+), 16 deletions(-)

diff --git a/docs/SPECIFICATION.md b/docs/SPECIFICATION.md
index c56a2d2..2f27c77 100644
--- a/docs/SPECIFICATION.md
+++ b/docs/SPECIFICATION.md
@@ -1,6 +1,7 @@
 
 # Draft Specification
 
+- Conventions used in this document
 - Encrypted file format
 - Payload
   - Comments
@@ -22,6 +23,18 @@
 
 ---
 
+## Conventions used in this document
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) [[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)] [[RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)] when, and only when, they appear in all capitals, as shown here.
+
+`||` denotes concatenation.
+`=` denotes assignment.
+`,` denotes separate parameters.
+`0x` followed by two hexadecimal characters denotes a byte value in the 0-255 range.
+`++` denotes incremented by one in little-endian.
+
+---
+
 ## Encrypted file format
 
 Cryptoblob structure:
@@ -72,6 +85,8 @@ Alternative scheme:
 cryptoblob = header_salt || header_pad || ciphertext || MAC tag || footer_pad || footer_salt
 ```
 
+---
+
 ## Payload
 
 Payload consists of Comments up to 512 bytes and File contents from 0 bytes.
@@ -91,6 +106,8 @@ The payload file could be:
 - regular file;
 - block device.
 
+---
+
 ## Input keying material
 
 `tird` can use passhrases and contents of keyfiles to derive one-time keys.
@@ -103,6 +120,8 @@ User can specify none, one or multiple keyfile paths.
 
 User can specify none, one or multiple passphrases.
 
+---
+
 ## Salt
 
 Creating `blake2_salt` and `argon2_salt`:
@@ -129,6 +148,8 @@ blake2_salt = header_salt[:8] || footer_salt[:8]
 argon2_salt = header_salt[-8:] || footer_salt[-8:]
 ```
 
+---
+
 ## Key derivation scheme
 
 How to get one-time keys (encryption key, padding key, MAC key) from input keying material and salt.
@@ -170,6 +191,8 @@ ChaCha20    pad_key1:16  pad_key2:16   keyed BLAKE2b-512
       pad size           header_pad and footer_pad
 ```
 
+---
+
 ## Keys utilization
 
 ### Padding
@@ -208,6 +231,8 @@ MAC tag = BLAKE2b-512(MAC message, MAC key)
 Fake MAC tag = urandom(64)
 ```
 
+---
+
 ## Layer cake: embed and extract
 
 ### Just embed and extract (no encryption)
@@ -215,27 +240,29 @@ Fake MAC tag = urandom(64)
 Container file format
 
 ```
-0              start          end
-|              |              |
-+--------------+--------------+----------+
-|              |   message    |          |
-+--------------+--------------+----------+
+0    start      end     start      end
+|    |          |       |          |
++----+----------+-------+----------+-----+
+|    | message1 |       | message2 |     |
++----+----------+-------+----------+-----+
 ```
 
 ### Encrypt & embed, Extract & decrypt
 
-Container file format
+Container file format:
 
 ```
-0              start          end
-|              |              |
-+--------------+--------------+----------+
-|              |  cryptoblob  |          |
-+--------------+--------------+----------+
+0    start         end     start         end
+|    |             |       |             |
++----+-------------+-------+-------------+------+
+|    | cryptoblob1 |       | cryptoblob2 |      |
++----+-------------+-------+-------------+------+
 ```
 
 Write a cryptoblob over a container file.
 
+---
+
 ## Creating files with random data
 
 Create a new file and write random data with chunks up to 128 KiB.
@@ -244,6 +271,8 @@ Create a new file and write random data with chunks up to 128 KiB.
 output file contents = urandom(size)
 ```
 
+---
+
 ## Overwriting file contents with random data
 
 Owerwrite file contents with random data from the start position to the end position.
@@ -251,9 +280,9 @@ Owerwrite file contents with random data from the start position to the end posi
 Use chunks up to 128 KiB.
 
 ```
-0              start         end
-|              |             |
-+--------------+-------------+----------+
-|              | random data |          |
-+--------------+-------------+----------+
+0       start         end
+|       |             |
++-------+-------------+-----+
+|       | random data |     |
++-------+-------------+-----+
 ```