Adding real examples and more explanations

README.md

@@ -38,23 +38,23 @@ Options:
    -d --display          Display the collisions in real time
    -o, --output <filepath>      Specify an output file
 Example:
-    ./HashQuake -w dictionary.txt 'python3 md5.py'
-    ./HashQuake -s 8 -o report.txt -d './sha256'
-
+    ./HashQuake -w wordlist.txt 'python3 examples/custom_hash1.py'
+    ./HashQuake -t 8 -o report.txt -d './examples/custom_hash2'
 ```
 
 ### Examples
 
-- Use a custom wordlist and run the `md5.py` python3 script:
+- Use a custom wordlist and run the `custom_hash1.py` python3 script:
 
 ```
-./HashQuake -w wordlist.txt 'python3 md5.py'
+./HashQuake -w wordlist.txt 'python3 examples/custom_hash1.py'
 ```
 
-- Generate words with a length of 8 characters, save the output to a file, display collisions in real-time running the `sha256` binary.
+- Generate words with a length of 8 characters, save the output to a file, display collisions in real-time running the `custom_hash2` binary.
 ```
-./HashQuake -s 8 -o report.txt -d './sha256'
+./HashQuake -t 8 -o report.txt -d './examples/custom_hash2'
 ```
+make sure the binary exist, you can compile it first using `gcc examples/custom_hash2.c -o examples/custom_hash2`
 
 ## Importing Your Own Hash Functions
 

examples/custom_hash1.py

@@ -0,0 +1,20 @@
+import sys
+from base64 import b64encode
+
+def hashing(word: str):
+    """
+    Convert a string to its base64 representation after converting it to lowercase.
+    This is a really weak hash function as it is easily reversible and case-insensitive (will generate collisions beetween 'AA','aa', 'Aa' and 'aA').
+    
+    Example:
+        >>> hashing("Appl3")
+        'YXBwbDM='  # Process: "Appl3" -> "appl3" -> bytes -> base64
+    
+    """
+    return b64encode(word.lower().encode()).decode()
+
+if len(sys.argv) < 2:
+    print("Error: No word specified.")
+    sys.exit(1)
+
+print(hashing(" ".join(sys.argv[1:])))

examples/custom_hash2.c

@@ -0,0 +1,77 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+char* hashing(const char* word) {
+    // This function creates a 16-bit hash by processing the input string in 2-byte blocks
+    // and XORing them together. Each block is created by shifting the first byte left by 8
+    // and combining it with the second byte using OR.
+
+    // It will cause collisions when:
+    // 1. Two strings have the same pairs of bytes in different orders (e.g., "abcd" vs "cdab")
+    // 2. Strings have repeating 2-byte patterns that cancel out through XOR
+    // 3. Different strings whose 2-byte blocks XOR to the same value
+    // 4. Strings longer than 2 bytes where subsequent blocks cancel out previous ones
+
+    // Example:
+    // "ABCDEF" -> Process as blocks "AB" "CD" "EF"
+    // Block 1: 'A'(65) << 8 | 'B'(66)   = 0x4142
+    // Block 2: 'C'(67) << 8 | 'D'(68)   = 0x4344
+    // Block 3: 'E'(69) << 8 | 'F'(70)   = 0x4546
+    // Result: 0x4142 ^ 0x4344 ^ 0x4546  = 0x4740
+    // hash value encoded in base32: I5AA
+    // final hash value: I5AA
+
+    static char hash[5];
+    size_t len = strlen(word);
+    unsigned short result = 0;
+
+    for (size_t i = 0; i < len; i += 2) {
+        unsigned short block = (unsigned char)word[i];
+
+        if (i + 1 < len)
+            block = (block << 8) | (unsigned char)word[i + 1];
+
+        result ^= block;
+    }
+
+    // Convert to base32
+    static const char base32_chars[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+    hash[0] = base32_chars[(result >> 11) & 0x1F];
+    hash[1] = base32_chars[(result >> 6) & 0x1F];
+    hash[2] = base32_chars[(result >> 1) & 0x1F];
+    hash[3] = base32_chars[(result & 0x01) << 4];
+    hash[4] = '\0';
+
+    return hash;
+
+}
+
+
+
+int main(int argc, char* argv[]) {
+    if (argc < 2) {
+        printf("Error: No word specified.\n");
+        return 1;
+    }
+    size_t len = 0;
+    for (int i = 1; i < argc; i++) {
+        len += strlen(argv[i]) + 1;
+    }
+    char* result = malloc(len);
+    if (result == NULL) {
+        fprintf(stderr, "Memory allocation failed.\n");
+        return 1;
+    }
+    result[0] = '\0';
+    for (int i = 1; i < argc; i++) {
+        strcat(result, argv[i]);
+        if (i < argc - 1)
+            strcat(result, " ");
+    }
+    printf("%s\n", hashing(result));
+    free(result);
+    return 0;
+}
+

src/collider.go

@@ -9,6 +9,7 @@ import (
     "sync"
 )
 
+// TODO: display current word in bottom
 const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 
 func generateWords(word []byte, wordLength int) []string {

src/help.go

@@ -8,9 +8,6 @@ import (
 func showHelpMessage() {
 	helpMessage := `Usage:
     ./HashQuake [OPTIONS] <command to run the algorithm>
-Disclaimer:
-   The program will run the command and add the word as the last argument.
-   The program expects the hash to appear in stdout.
 Options:
    -h, --help            Display this help message
    -v, --version         Display the version of the program
@@ -20,8 +17,8 @@ Options:
    -d --display          Display the collisions in real time
    -o, --output <filepath>      Specify an output file
 Example:
-    ./HashQuake -w dictionary.txt 'python3 md5.py'
-    ./HashQuake -s 8 -o report.txt -d './sha256'
+    ./HashQuake -w wordlist.txt 'python3 examples/custom_hash1.py'
+    ./HashQuake -t 8 -o report.txt -d './examples/custom_hash2'
 `
 	fmt.Print(helpMessage)
 	os.Exit(0)

src/main.go

@@ -67,4 +67,5 @@ func main() {
 	}
 	fmt.Printf("Colliding with %d threads...\n", *threads)
 	collide(*wordLength, *displayMode, *wordlistFile, *outputFile, *threads, algorithmCommand)
+	fmt.Printf("Done.\n")
 }