Implement AES encryption algorithm

.github/workflows/tests.yml

@@ -1,10 +1,6 @@
 name: tests
 
-on:
-  push:
-    branches:
-      - main
-  pull_request:
+on: [push, pull_request]
 
 jobs:
   test:
@@ -23,9 +19,9 @@ jobs:
             nasm \
             nlohmann-json3-dev
 
-      - name: Download Circom Binary v2.1.5
+      - name: Download Circom Binary v2.1.5\8
         run: |
-          wget -qO /home/runner/work/circom https://github.com/iden3/circom/releases/download/v2.1.5/circom-linux-amd64
+          wget -qO /home/runner/work/circom https://github.com/iden3/circom/releases/download/v2.1.8/circom-linux-amd64
           chmod +x /home/runner/work/circom
           sudo mv /home/runner/work/circom /bin/circom
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 crema-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,131 +1,43 @@
-# Circomkit Examples
+# aes-circom
 
-In this repository, we are using [Circomkit](https://github.com/erhant/circomkit) to test some example circuits using Mocha. The circuits and the statements that they prove are as follows:
-
-- **Multiplier**: "I know `n` factors that make up some number".
-- **Fibonacci**: "I know the `n`'th Fibonacci number".
-- **SHA256**: "I know the `n`-byte preimage of some SHA256 digest".
-- **Sudoku**: "I know the solution to some `(n^2)x(n^2)` Sudoku puzzle".
-- **Floating-Point Addition**: "I know two floating-point numbers that make up some number with `e` exponent and `m` mantissa bits." (adapted from [Berkeley ZKP MOOC 2023 - Lab](https://github.com/rdi-berkeley/zkp-mooc-lab)).
-
-## CLI Usage
-
-To use Circomkit CLI with a circuit, let's say for Sudoku 9x9, we follow the steps below:
-
-1. We write a circuit config in `circuits.json` with the desired parameters. In this case, we are working with the 9x9 Sudoku solution circuit, and the board size is calculated by the square of our template parameter so we should give 3. Furthermore, `puzzle` is a public input so we should specify that too.
-
-```json
-{
-  "sudoku_9x9": {
-    "file": "sudoku",
-    "template": "Sudoku",
-    "pubs": ["puzzle"],
-    "params": [3]
-  }
-}
-```
-
-2. Compile the circuit with Circomkit, providing the same circuit name as in `circuits.json`:
-
-```sh
-npx circomkit compile sudoku_9x9
-
-# print circuit info if you want to
-npx circomkit info sudoku_9x9
-```
-
-3. Commence circuit-specific setup. Normally, this requires us to download a Phase-1 PTAU file and provide it's path; however, Circomkit can determine the required PTAU and download it automatically when using `bn128` curve, thanks to [Perpetual Powers of Tau](https://github.com/privacy-scaling-explorations/perpetualpowersoftau). In this case, `sudoku_9x9` circuit has 4617 constraints, so Circomkit will download `powersOfTau28_hez_final_13.ptau` (see [here](https://github.com/iden3/snarkjs#7-prepare-phase-2)).
-
-```sh
-npx circomkit setup sudoku_9x9
+This repository contains generic implementation for AES encryption in Circom.
 
-# alternative: provide the PTAU yourself
-npx circomkit setup sudoku_9x9 <path-to-ptau>
-```
+## AES
 
-4. Prepare your input file under `./inputs/sudoku_9x9/default.json`.
+AES is a symmetric encryption algorithm that was established by the U.S. National Institute of Standards and Technology (NIST) in 2001. It is a subset of the Rijndael block cipher. AES has a fixed block size of 128 bits and a key size of 128, 192, or 256 bits. The algorithm is based on a design principle known as a substitution-permutation network (SPN).It is a symmetric block cipher that can encrypt (encipher) and decrypt (decipher) information. Encryption converts data to an unintelligible form called ciphertext; decrypting the ciphertext converts the data back into its original form, called plaintext. The symmetric key signifies that the same key is used for both encryption and decryption.
 
-```json
-{
-  "solution": [
-    [1, 9, 4, 8, 6, 5, 2, 3, 7],
-    [7, 3, 5, 4, 1, 2, 9, 6, 8],
-    [8, 6, 2, 3, 9, 7, 1, 4, 5],
-    [9, 2, 1, 7, 4, 8, 3, 5, 6],
-    [6, 7, 8, 5, 3, 1, 4, 2, 9],
-    [4, 5, 3, 9, 2, 6, 8, 7, 1],
-    [3, 8, 9, 6, 5, 4, 7, 1, 2],
-    [2, 4, 6, 1, 7, 9, 5, 8, 3],
-    [5, 1, 7, 2, 8, 3, 6, 9, 4]
-  ],
-  "puzzle": [
-    [0, 0, 0, 8, 6, 0, 2, 3, 0],
-    [7, 0, 5, 0, 0, 0, 9, 0, 8],
-    [0, 6, 0, 3, 0, 7, 0, 4, 0],
-    [0, 2, 0, 7, 0, 8, 0, 5, 0],
-    [0, 7, 8, 5, 0, 0, 0, 0, 0],
-    [4, 0, 0, 9, 0, 6, 0, 7, 0],
-    [3, 0, 9, 0, 5, 0, 7, 0, 2],
-    [0, 4, 0, 1, 0, 9, 0, 8, 0],
-    [5, 0, 7, 0, 8, 0, 0, 9, 4]
-  ]
-}
-```
-
-5. We are ready to create a proof!
-
-```sh
-npx circomkit prove sudoku_9x9 default
-```
+Read more about AES here := [FIPS 197](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197-upd1.pdf).
+Simple Rust implementation of AES can be found here := [tinyaes](https://docs.rs/crate/tinyaes/latest/source/src/aes_core.rs)
 
-6. We can then verify our proof. You can try and modify the public input at `./build/sudoku_9x9/default/public.json` and see if the proof verifies or not!
+## Circuit
 
-```sh
-npx circomkit verify sudoku_9x9 default
-```
+The circuits contain components for AES forward encryption. The implementation strictly follows the AES standard mentioned in the FIPS 197 document. The circuit is designed to be generic and can be used for any key size (128, 192, 256 bits) and block size (128 bits).
 
-## In-Code Usage
+Check the [Cipher](./circuits/aes.circom) and [KeyExpansion](./circuits/key_expansion.circom) circuits for visual representation of the design.
 
-If you would like to use Circomkit within the code itself, rather than the CLI, you can see the example at `src/index.ts`. You can `yarn start` to see it in action.
+## Design Decisions
 
-```ts
-// create circomkit
-const circomkit = new Circomkit({
-  protocol: "groth16",
-});
+The circuit only support the forward encryption of AES as we believe that the proof of computation for any proprietary use case can be refactored to use the forward encryption instead of the decryption. 
 
-// artifacts output at `build/multiplier_3` directory
-await circomkit.compile("multiplier_3", {
-  file: "multiplier",
-  template: "Multiplier",
-  params: [3],
-});
+ 💡 Create an issue if you think that the decryption circuit is necessary.
 
-// proof & public signals at `build/multiplier_3/my_input` directory
-await circomkit.prove("multiplier_3", "my_input", { in: [3, 5, 7] });
+## Circomkit
 
-// verify with proof & public signals at `build/multiplier_3/my_input`
-const ok = await circomkit.verify("multiplier_3", "my_input");
-if (ok) {
-  circomkit.log("Proof verified!", "success");
-} else {
-  circomkit.log("Verification failed.", "error");
-}
-```
+In this repository, we are using [Circomkit](https://github.com/erhant/circomkit) to test some example circuits using Mocha. The circuits and the statements that they prove are as follows:
 
-## Configuration
+### Configuration
 
 Circomkit checks for `circomkit.json` to override it's default configurations. We could for example change the target version, prime field and the proof system by setting `circomkit.json` to be:
 
 ```json
 {
-  "version": "2.1.2",
+  "version": "2.1.8",
   "protocol": "plonk",
   "prime": "bls12381"
 }
 ```
 
-## Testing
+### Testing
 
 You can use the following commands to test the circuits:
 
@@ -134,5 +46,15 @@ You can use the following commands to test the circuits:
 yarn test
 
 # test a specific circuit
-yarn test -g <circuit-name>
+yarn test -g <template-name>
 ```
+
+## Roadmap
+
+- [x] AES Forward Encryption Circuit
+- [ ] Add AES-CTR mode (priority for ECIES implementaion)
+- [ ] Add all other modes adhering to [NIST standards](https://nvlpubs.nist.gov/nistpubs/legacy/sp/nistspecialpublication800-38a.pdf)
+
+## Contribution
+
+Feel free to contribute to this repository by creating issues or pull requests. We are open to any suggestions or improvements.

circomkit.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.2",
-  "proofSystem": "plonk",
+  "version": "2.1.8",
+  "proofSystem": "groth16",
   "curve": "bn128"
 }

circuits.json

@@ -1,7 +1,7 @@
 {
-  "fibonacci_11": {
-    "file": "fibonacci",
-    "template": "Fibonacci",
-    "params": [11]
+  "cipher_4": {
+    "file": "cipher",
+    "template": "Cipher",
+    "params": [4]
   }
 }

circuits/cipher.circom

@@ -0,0 +1,106 @@
+pragma circom 2.1.8;
+
+include "key_expansion.circom";
+include "circomlib/circuits/comparators.circom";
+include "circomlib/circuits/bitify.circom";
+include "circomlib/circuits/gates.circom";
+include "transformations.circom";
+include "mix_columns.circom";
+
+// Cipher Process
+// nk: number of keys which can be 4, 6, 8
+// AES 128, 192, 256 have 10, 12, 14 rounds.
+// Input Block   Initial Round Key          Round Key             Final Round Key
+//     │                │                       │                       │
+//     ▼                ▼                       ▼                       ▼
+//  ┌─────────┐    ┌──────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐
+//  │ Block   │──► │   Add    │ │  Sub   │ │   Mix    │ │  Sub   │ │   Add    │
+//  │         │    │  Round   │ │ Bytes  │ │ Columns  │ │ Bytes  │ │  Round   │
+//  │         │    │   Key    │ │        │ │          │ │        │ │   Key    │
+//  └─────────┘    └────┬─────┘ └───┬────┘ └────┬─────┘ └───┬────┘ └────┬─────┘
+//                      │           │           │           │           │
+//                      ▼           ▼           ▼           ▼           ▼
+//                 ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
+//                 │ Round 0 │ │ Round 1 │ │ Round 2 │ │ Round   │ │  Final  │
+//                 │         │ │   to    │ │   to    │ │ Nr - 1  │ │  Round  │
+//                 │         │ │ Nr - 2  │ │ Nr - 1  │ │         │ │         │
+//                 └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────┬────┘
+//                                                                      │
+//                                                                      ▼
+//                                                                 Ciphertext
+
+// @param nk: number of keys which can be 4, 6, 8
+// @inputs block: 4x4 matrix representing the input block
+// @inputs key: array of nk*4 bytes representing the key
+// @outputs cipher: 4x4 matrix representing the output block
+template Cipher(nk){
+        assert(nk == 4 || nk == 6 || nk == 8 );
+        signal input block[4][4];
+        signal output cipher[4][4];
+        signal input key[nk * 4];
+
+        var nr = Rounds(nk);
+
+        component keyExpansion = KeyExpansion(nk,nr);
+        keyExpansion.key <== key;
+
+        component addRoundKey[nr+1]; 
+        component subBytes[nr];
+        component shiftRows[nr];
+        component mixColumns[nr-1];
+
+        signal interBlock[nr][4][4];
+
+        addRoundKey[0] = AddRoundKey();
+        addRoundKey[0].state <== block;
+        for (var i = 0; i < 4; i++) {
+                addRoundKey[0].roundKey[i] <== keyExpansion.keyExpanded[i];
+        }
+
+        interBlock[0] <== addRoundKey[0].newState;
+        for (var i = 1; i < nr; i++) {
+                subBytes[i-1] = SubBlock();
+                subBytes[i-1].state <== interBlock[i-1];
+
+                shiftRows[i-1] = ShiftRows();
+                shiftRows[i-1].state <== subBytes[i-1].newState;
+
+                mixColumns[i-1] = MixColumns();
+                mixColumns[i-1].state <== shiftRows[i-1].newState;
+
+                addRoundKey[i] = AddRoundKey();
+                addRoundKey[i].state <== mixColumns[i-1].out;
+                 for (var j = 0; j < 4; j++) {
+                        addRoundKey[i].roundKey[j] <== keyExpansion.keyExpanded[j + (i * 4)];
+                }
+
+                interBlock[i] <== addRoundKey[i].newState;
+        }
+
+        subBytes[nr-1] = SubBlock();
+        subBytes[nr-1].state <== interBlock[nr-1];
+
+        shiftRows[nr-1] = ShiftRows();
+        shiftRows[nr-1].state <== subBytes[nr-1].newState;
+
+        addRoundKey[nr] = AddRoundKey();
+        addRoundKey[nr].state <== shiftRows[nr-1].newState;
+        for (var i = 0; i < 4; i++) {
+                addRoundKey[nr].roundKey[i] <== keyExpansion.keyExpanded[i + (nr * 4)];
+        }
+
+        cipher <== addRoundKey[nr].newState;
+}
+
+// @param nk: number of keys which can be 4, 6, 8
+// @returns number of rounds
+// AES 128, 192, 256 have 10, 12, 14 rounds.
+function Rounds (nk) {
+    if (nk == 4) {
+       return 10;
+    } else if (nk == 6) {
+        return 12;
+    } else {
+        return 14;
+    }
+}