From 1fd74c6ec388b863857c9a5e4379470a87033138 Mon Sep 17 00:00:00 2001
From: Sebastian Hugentobler <sebastian@vanwa.ch>
Date: Sat, 19 Mar 2022 18:14:16 +0100
Subject: [PATCH] add documentation to spn functions

---
 src/main/java/ch/fhnw/kry/SPN.java | 86 +++++++++++++++++++++++++-----
 1 file changed, 72 insertions(+), 14 deletions(-)

diff --git a/src/main/java/ch/fhnw/kry/SPN.java b/src/main/java/ch/fhnw/kry/SPN.java
index a0f83b3..33a14a4 100644
--- a/src/main/java/ch/fhnw/kry/SPN.java
+++ b/src/main/java/ch/fhnw/kry/SPN.java
@@ -67,36 +67,59 @@ public class SPN {
         return null;
     }
 
+    /**
+     * Encrypt a block with the defined SPN.
+     *
+     * @param key Key for encryption (round keys get derived from this).
+     * @param x Input block (high 16 bits get ignored).
+     * @return Encrypted block.
+     */
     public int encryptBlock(int key, int x) {
-        x = init(key, x, 0);
+        x = init(key, x, 0); // initialer Weisschritt
 
-        for (int i = 1; i < 4; i++) {
-            x = substitution(x, SBOX);
-            x = permutation(x);
-            x ^= k(key, i);
+        for (int i = 1; i < 4; i++) { // for rounds > 0 && < r
+            x = substitution(x, SBOX); // run through s-box
+            x = permutation(x); // permutate
+            x ^= k(key, i); // xor with derived round key
         }
 
-        x = substitution(x, SBOX);
-        x ^= k(key, 4);
+        x = substitution(x, SBOX); // run through s-box
+        x ^= k(key, 4); // xor with last round key
 
         return x;
     }
 
+    /**
+     * Decrypt a block with the defined SPN.
+     *
+     * @param key Key for decryption (round keys get derived from this).
+     * @param x Encrypted block (high 16 bits get ignored).
+     * @return Decrypted block.
+     */
     public int decryptBlock(int key, int x) {
-        x = init(key, x, 4);
+        x = init(key, x, 4); // initialer Weisschritt
 
-        for (int i = 3; i > 0; i--) {
-            x = substitution(x, SBOX_REVERSE);
-            x = permutation(x);
-            x ^= permutation(k(key, i));
+        for (int i = 3; i > 0; i--) { // for rounds > 0 && < r, going in reverse
+            x = substitution(x, SBOX_REVERSE); // run through reverse s-box
+            x = permutation(x); // permutate
+            x ^= permutation(k(key, i)); // xor with permutated derived round key
         }
 
-        x = substitution(x, SBOX_REVERSE);
-        x ^= k(key, 0);
+        x = substitution(x, SBOX_REVERSE); // run through reverse s-box
+        x ^= k(key, 0); // xor with round key 0
 
         return x;
     }
 
+    /**
+     * Derive a round key from a key by multiplying
+     * the round number with four and taking the next 16
+     * bits from that position in the key.
+     *
+     * @param key Key as input.
+     * @param i Round number (starts at 0).
+     * @return Derived key.
+     */
     public int k(int key, int i) {
         i *= 4;
         int mask = 0xFFFF_0000 >>> i;
@@ -104,10 +127,27 @@ public class SPN {
         return (key & mask) >>> ROUND_KEY_LENGTH - i;
     }
 
+    /**
+     * Initialer Weisschritt.
+     *
+     * XOR an input with the key of a specific round.
+     *
+     * @param key Key to derive the round key.
+     * @param x Input.
+     * @param r Round number (starts at 0).
+     * @return Input xored with the derived round key.
+     */
     public int init(int key, int x, int r) {
         return x ^ k(key, r);
     }
 
+    /**
+     * Permutate an input by swapping all its lower 16 bits as defined
+     * by a map.
+     *
+     * @param x Initial state (the high 16 bits of the integer are ignored).
+     * @return End state, after running all permutations.
+     */
     public int permutation(int x) {
         Map<Integer, Boolean> blocked = new HashMap<>();
 
@@ -121,6 +161,13 @@ public class SPN {
         return x;
     }
 
+    /**
+     * Substitute every four bits of an input by running them through an S-Box.
+     *
+     * @param x Initial state (the high 16 bits of the integer are ignored).
+     * @param sbox A mapping consisting of hex keys and values.
+     * @return End state, after running all substitutions.
+     */
     public int substitution(int x, Map<Integer, Integer> sbox) {
         int mask = 0xF000;
         for (int i = 0; i < 4; i++) {
@@ -135,7 +182,18 @@ public class SPN {
         return x;
     }
 
+    /**
+     * Swap two bits.
+     *
+     * Because we work with blocks of 16 bits, the high bits of the int input x are ignored.
+     *
+     * @param x Value where the bits get swapped (high 16 bits get ignored).
+     * @param a Position of the first bit to swap.
+     * @param b Position of the second bit to swap.
+     * @return Input value with bits in position a and b swapped.
+     */
     public int swapBits(int x, int a, int b) {
+        // calculate the position respective to the 32 bits, hence ignoring the high 16 bits of x
         a = 15 - a;
         b = 15 - b;