Update README.md for modes of operation (#158)

* Update CBC and ECB readme

* Update modes/README.md and add ascii to ghash and gctr

* Update CTR image

* minor readme change

* fix lint

* fix ascii diagram errors

README.md

@@ -50,10 +50,18 @@ to run example code.
 
 ### Encryption
 
+####  Asymmetric
 - [RSA](src/encryption/asymmetric/rsa/README.md)
-- [DES](src/encryption/symmetric/des/README.md)
-- [AES](src/encryption/symmetric/aes/README.md)
-- [ChaCha](src/encryption/symmetric/chacha/README.md)
+
+#### Symmetric
+
+- **Ciphers:**
+    + [DES](src/encryption/symmetric/des/README.md)
+    + [AES](src/encryption/symmetric/aes/README.md)
+    + [ChaCha](src/encryption/symmetric/chacha/README.md)
+
+- [**Modes of Operation**](src/encryption/symmetric/modes/README.md)
+    + ECB, CBC, CTR, GCM
 
 ### Hash
 

src/encryption/symmetric/modes/README.md

@@ -8,32 +8,60 @@ Appropriate padding has to be performed for some modes, as block ciphers only wo
 
 Let's go into detail about Block cipher's [mode of operation](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation):
 
-## ECB: Electronic codebook
-- deterministic, so not CPA-secure.
-- can be parallelised easily.
-## CBC: cipher block chaining
-- IV chosen uniformly and $c_{0}=IV$, then $c_{i}=F_{k}(c_{i-1} \oplus m_{i})$
-- sequential in nature, although decryption can be parallelised as inputs to block cipher's encryption is just the ciphertext
-- chained CBC, where ciphertext is chained for subsequent encryptions.
-  - But it's not CPA secure, as attacker can distinguish between PRF and uniform random function by choosing appropriate text in second encryption.
+## ECB: Electronic codebook (INSECURE)
+
+The encryption operation in ECB can be viewed as,
+
+![ECB](./figure_ecb.svg)
+
+- It is the simplest mode of encryption but is not secure.
+- In this, we independently apply the block cipher on each block of plaintext. 
+- The algorithm is deterministic, hence it is not secure against Chosen-plaintext Attack(CPA).
+- It can be parallelized easily.
+
+## CBC: Cipher Block Chaining
+
+The encryption operation in CBC can be viewed as,
+
+![CBC](./figure_cbc.svg)
+
+- It is a CPA-secure mode of operation.
+- The first ciphertext block is called an Initialisation Vector(IV), which is chosen uniformly at random.
+- It is defined as, $$C_{0}=IV, \quad C_{i}=Enc_{K}(C_{i-1} \oplus M_{i}) $$
+where,
+    + $C_{i}$ represents blocks of ciphertext.
+    + $Enc_{K}$ is the block cipher with key $K$
+    + $M_{i}$ represents the $i$-th plaintext block
+    + and $i$ ranges from 1 to N, the number of blocks required by the plaintext.
+
+- It is sequential in nature, although decryption can be parallelized as inputs to block cipher's encryption is just the ciphertext.
+- **Chained CBC**: A variant of CBC where ciphertext is chained for subsequent encryptions.
+  + But it's not CPA secure, as an attacker can distinguish between PRF and uniform random function by choosing appropriate text in second encryption.
+  + See the [code example](../../../../examples/aes_chained_cbc.rs) that demonstrates this vulnerability!
+
 ## OFB: output feedback
-- IV is chosen uniformly and $y_{0}:=IV$, then $y_{i}=F_{k}(y_{i-1})$ and $c_{i}=y_{i} \oplus m_{i}$.
-- this allows $F_{k}$ to not be invertible, and can be simply a PRF.
+
+The encryption operation in OFB can be viewed as,
+
+![OFB](./figure_ofb.svg)
+
+- IV is chosen uniformly and $Y_{0}:=IV$, then $Y_{i}=Enc_{k}(Y_{i-1})$ and $C_{i}=Y_{i} \oplus M_{i}$.
+- This allows $Enc_{k}$ to not be invertible, and can be simply a PRF.
 - Due to this, OFB can be used to encrypt plaintext of arbitrary lengths and not have to be multiple of block length.
-- pseudorandom stream can be preprocessed and then encryption can be really fast.
-- it's stateful variant can be used to instantiate stream cipher's synchronised mode of operation and is secure.
+- Pseudorandom Stream can be preprocessed and then encryption can be really fast.
+- It's stateful variant can be used to instantiate stream cipher's synchronised mode of operation and is secure.
+
 ## CTR: counter mode
-- can be viewed as unsynchronised stream cipher mode, where $y_{i}=F_{k}(\langle IV \parallel i\rangle)$ for binary string $i = 1,2,\dots,$ and $c_{i}=y_{i}\oplus m_{i}$.
-- this again allows $F_{k}$ to not be invertible and can be instantiated with a Pseudorandom function.
-- can be fully parallelised.
-```mermaid
-flowchart TB
-IV1[IV]---->IV2[IV]
-IV3["IV||1"]-->Fk1[F_k]-->xor1["⨁"]-->c1
-m1-->xor1
-IV4["IV||2"]-->Fk2[F_k]-->xor2["⨁"]-->c2
-m2-->xor2
-```
+
+The encryption operation in CTR can be viewed as,
+
+![CTR](./figure_ctr.svg)
+
+- Like OFB, CTR converts a block cipher to a stream cipher. where the keystream, called the Counter Block, is generated using the nonce/IV concatenated with a counter, which is 
+incremented for successive blocks.
+- Thus, it can be viewed as unsynchronised stream cipher mode, where $Y_{i}=Enc_{K}(\langle IV \parallel i\rangle)$ for the binary string $i = 1,2,\dots,$ and $c_{i}=y_{i}\oplus m_{i}$.
+- This again allows $Enc_{K}$ to not be invertible and can be instantiated with a Pseudorandom function.
+- It can be fully parallelized.
 
 ## GCM: Galois/Counter Mode
 

src/encryption/symmetric/modes/gcm.rs

@@ -1,5 +1,35 @@
 //! Implementation of GCM cipher mode of operation based on NIST GCM specification.
 //! [The Galois/Counter Mode of Operation (GCM)](http://www.csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-revised-spec.pdf)
+//!
+//! GCM has two parts GCTR (used of encryption/decryption) and GHASH (used for authentication).
+//!
+//! GCTR is similar to CTR mode of operation. ASCII diagram of GCTR, courtesy of
+//! @0xJepsen.
+//!            -------------           inc           -------------
+//!            |    ICB    | ----------------------> |    CB2    |
+//!            -------------                         -------------
+//!                  |                                      |
+//!                  v                                      v
+//!            ------------                           ------------
+//!            |  CIPH_K  |                           |  CIPH_K  |
+//!            ------------                           ------------
+//!                  |                                      |
+//!                  v                                      v
+//!             ------------                           ------------
+//!             |    X1    |                           |     X2   |
+//!             ------------                           ------------
+//!                   |                                      |
+//!                   v                       ---------      v
+//!                  XOR                   -->|  Y_1  |---> XOR
+//!                   |                    |  ---------      |
+//!                   v                    |                 v
+//!               --------                 |              --------
+//!               |  Y1  |------------------              |  Y2  |
+//!               --------                                --------
+//!                   |                                       |
+//!                   v                                       v
+//!
+//! GCTR_K (ICB, X1 || X2 || ... || X_n*) = Y1 || Y2 || ... || Y_n*.
 
 use super::ctr::CTR;
 use crate::{

src/hashes/ghash.rs

@@ -1,6 +1,25 @@
-//! Implementation of [`GHASH`] algorithm which is used in AES-GCM.
+//! Implementation of [`GHASH`] algorithm which is used in AES-GCM to compute the authentication
+//! tag.
 //! Based on GCM specification given by NIST:
 //! [The Galois/Counter Mode of Operation (GCM)](http://www.csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-revised-spec.pdf)
+//!
+//! ASCII diagram of GHASH, courtesy of @0xJepsen:
+//!           X1                      X2          ...          XM
+//!           |                       |                        |
+//!           |                       v                        v
+//!           |                  ------------             ------------
+//!           |           ------>|   XOR    |      ------>|   XOR    |
+//!           |           |      -----┬------      |      -----┬------
+//!           |           |           |            |           |
+//!           v           |           v            |           v
+//!  ------------------   |   ------------------   |   ------------------
+//!  | multiply by H  |   |   | multiply by H  |   |   | multiply by H  |
+//!  ---------┬--------   |   --------┬---------   |   --------┬---------
+//!           |           |           |            |           |
+//!           v           |           v            |           v
+//!      -----------      |      -----------       |      -----------
+//!      |  TAG1   | ------      |   TAG2  | -------      |   TAGM  |
+//!      -----------             -----------              -----------
 
 use core::array;