Update README

README.md

@@ -1,8 +1,8 @@
-# slowkey
+# SlowKey: Advanced Key Derivation Tool Using Scrypt, Argon2id, SHA2, and SHA3
 
 [![Build Status](https://github.com/lbeder/slowkey/actions/workflows/ci.yml/badge.svg)](https://github.com/lbeder/slowkey/actions/workflows/ci.yml)
 
-## SlowKey: Advanced Key Derivation Tool Using Scrypt, Argon2id, SHA2, and SHA3
+## Introduction
 
 SlowKey is a cutting-edge [Key Derivation Function](https://en.wikipedia.org/wiki/Key_derivation_function) (KDF) tool designed to enhance cryptographic security in various applications, from securing sensitive data to protecting user passwords. At its core, SlowKey leverages the power of three renowned cryptographic algorithms: [Scrypt](https://en.wikipedia.org/wiki/Scrypt), [Argon2](https://en.wikipedia.org/wiki/Argon2), [SHA2](https://en.wikipedia.org/wiki/SHA-2), and [SHA3](https://en.wikipedia.org/wiki/SHA-3), each selected for its unique strengths in ensuring data integrity and security.
 
@@ -14,6 +14,50 @@ Alongside Scrypt, and Argon2, SlowKey utilizes SHA2 and SHA3 for their exception
 
 A cornerstone of SlowKey's design philosophy is its commitment to resilience through diversity. By integrating Scrypt, SHA2, and SHA3 within its cryptographic framework, SlowKey not only capitalizes on the unique strengths of each algorithm but also ensures a level of security redundancy that is critical in the face of evolving cyber threats. This strategic mixture means that even if one of these algorithms were to be compromised or "broken" due to unforeseen vulnerabilities, the overall security scheme of SlowKey would remain robust and intact, safeguarded by the uncompromised integrity of the remaining algorithms. This approach mirrors the principle of layered security in cybersecurity, where multiple defensive strategies are employed to protect against a single point of failure. Consequently, SlowKey offers an advanced, forward-thinking solution that anticipates and mitigates the potential impact of future cryptographic breakthroughs or advancements in quantum computing that could threaten individual hash functions. Through this multi-algorithm strategy, SlowKey provides a safeguard against the entire spectrum of cryptographic attacks, ensuring long-term security for its users in a landscape where the only constant is change.
 
+## SlowKey Key Derivation Scheme
+
+The SlowKey Key Derivation Scheme is defined as follows:
+
+### Definitions
+
+- `Concatenate(data1, data2, data3)`: Function to concatenate `data1`, `data2`, and `data3`.
+- `SHA2(data)`: Function to compute SHA2 (SHA512) hash of `data`.
+- `SHA3(data)`: Function to compute SHA3 (Keccak512) hash of `data`.
+- `Scrypt(data, salt)`: Function to derive a key using Scrypt KDF with `data` and `salt`.
+- `Argon2id(data, salt)`: Function to derive a key using Argon2id KDF with `data` and `salt`.
+
+### Inputs
+
+- `password`: User's password.
+- `salt`: Unique salt for hashing.
+- `iterations`: Number of iterations the process should be repeated.
+
+### Output
+
+- `finalKey`: Derived key after all iterations.
+
+### Scheme
+
+```pseudo
+function deriveKey(password, salt, iterations):
+    previousResult = ""
+
+    for i from 1 to iterations:
+        step1 = SHA2(concatenate(previousResult, salt, password))
+        step2 = SHA3(concatenate(step1, salt, password))
+        step3 = Scrypt(step2, salt)
+        step4 = SHA2(concatenate(step3, salt, password))
+        step5 = SHA3(concatenate(step4, salt, password))
+        step6 = Argon2id(step5, salt)
+        previousResult = step6
+
+    finalStep1 = SHA2(concatenate(previousResult, salt, password))
+    finalStep2 = SHA3(concatenate(finalStep1, salt, password))
+    finalKey = finalStep2
+
+    return finalKey
+```
+
 ## Usage
 
 ### General
@@ -38,7 +82,7 @@ Derive a key using using Scrypt, Argon2, SHA2, and SHA3
 Usage: slowkey derive [OPTIONS]
 
 Options:
-  -i, --iterations <ITERATIONS>        Number of iterations (must be greater than 0 and lesser than or equal to 4294967295) [default: 100]
+  -i, --iterations <ITERATIONS>        Number of iterations (must be greater than 1 and lesser than or equal to 4294967295) [default: 100]
   -l, --length <LENGTH>                Length of the derived result (must be greater than 10 and lesser than or equal to 128) [default: 16]
       --scrypt-n <SCRYPT_N>            Scrypt CPU/memory cost parameter (must be lesser than 18446744073709551615) [default: 1048576]
       --scrypt-r <SCRYPT_R>            Scrypt block size parameter, which fine-tunes sequential memory read size and performance (must be greater than 0 and lesser than or equal to 4294967295) [default: 8]
@@ -187,31 +231,31 @@ Test vectors:
 
 ### #1
 
-* Password: "" (the empty string)
-* Salt: "SlowKeySlowKey16"
-* Iterations: 1
-* Length: 64
-* Scrypt Parameters:
-  * n: 1048576
-  * r: 8
-  * p: 1
-* Argon2id Parameters:
-  * m_cost: 2097152
-  * t_cost: 2
+- Password: "" (the empty string)
+- Salt: "SlowKeySlowKey16"
+- Iterations: 1
+- Length: 64
+- Scrypt Parameters:
+  - n: 1048576
+  - r: 8
+  - p: 1
+- Argon2id Parameters:
+  - m_cost: 2097152
+  - t_cost: 2
 
 ### #2
 
-* Password: "Hello World"
-* Salt: "SlowKeySlowKey16"
-* Iterations: 3
-* Length: 64
-* Scrypt Parameters:
-  * n: 1048576
-  * r: 8
-  * p: 1
-* Argon2id Parameters:
-  * m_cost: 2097152
-  * t_cost: 2
+- Password: "Hello World"
+- Salt: "SlowKeySlowKey16"
+- Iterations: 3
+- Length: 64
+- Scrypt Parameters:
+  - n: 1048576
+  - r: 8
+  - p: 1
+- Argon2id Parameters:
+  - m_cost: 2097152
+  - t_cost: 2
 
 Results should be: