{"id":19994284,"url":"https://github.com/nahiyan/cryptanalysis","last_synced_at":"2026-05-11T11:39:38.352Z","repository":{"id":234631338,"uuid":"542283954","full_name":"nahiyan/cryptanalysis","owner":"nahiyan","description":"A collection of tools to study the inversion or collision of truncated versions of MD4, MD5, SHA-256 with SAT solving using techniques such as Cube-and-Conquer, programmatic SAT, Dobbertin's Attack, and differential cryptanalysis.","archived":false,"fork":false,"pushed_at":"2024-08-02T03:55:01.000Z","size":2887,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-12T12:30:43.734Z","etag":null,"topics":["boolean-algebra","cadical","cdcl-solver","cryptominisat","cube-and-conquer","glucose","kissat","lookahead-solver","maplesat","march","sat-solver"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nahiyan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-27T20:50:21.000Z","updated_at":"2024-08-02T03:55:04.000Z","dependencies_parsed_at":"2024-04-20T06:32:17.001Z","dependency_job_id":"56da7f18-cf2b-4401-abd8-c5d3bd078b08","html_url":"https://github.com/nahiyan/cryptanalysis","commit_stats":null,"previous_names":["nahiyan/cryptanalysis"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahiyan%2Fcryptanalysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahiyan%2Fcryptanalysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahiyan%2Fcryptanalysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahiyan%2Fcryptanalysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nahiyan","download_url":"https://codeload.github.com/nahiyan/cryptanalysis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241435151,"owners_count":19962401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boolean-algebra","cadical","cdcl-solver","cryptominisat","cube-and-conquer","glucose","kissat","lookahead-solver","maplesat","march","sat-solver"],"created_at":"2024-11-13T04:54:37.436Z","updated_at":"2026-05-11T11:39:38.319Z","avatar_url":"https://github.com/nahiyan.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- TODO: Instruct people to use the root Makefile to build all the dependencies along with the cryptanalysis tool --\u003e\n\n# MD4, MD5, and SHA-256 Cryptanalysis\n\nThis repository houses a cryptanalysis tool aimed at (pre-image and collision) attacks on hash functions, namely MD4, MD5, and SHA-256, using SAT solvers. Techniques such as the [Dobbertin's attack](https://link.springer.com/content/pdf/10.1007/3-540-69710-1_19.pdf) and [Cube and Conquer using a Lookahead Solver](https://www.cs.utexas.edu/~marijn/publications/cube.pdf) are used to exploit the weakness of hash functions and increase feasibility of the attacks.\n\n# Prerequisities\n\nTo use the cryptanalysis tool, the following executables may be required (depending on your use-case):\n\n- [Kissat](https://github.com/arminbiere/kissat) as `kissat`\n- [CaDiCaL](https://github.com/arminbiere/cadical) as `cadical`\n- [March](https://github.com/BrianLi009/PhysicsCheck/tree/master/gen_cubes/march_cu) as `march_cu_pc` (suffixed with \"_pc\" for \"PhysicsCheck\")\n- [Transalg](https://gitlab.com/transalg/transalg) as `transalg`\n- [CryptoMiniSAT](https://github.com/msoos/cryptominisat) as `cryptominisat`\n- [MapleSAT](https://github.com/nahiyan/maplesat) as `maplesat`\n- [Glucose](https://github.com/mi-ki/glucose-syrup) as `glucose`\n- [NejatiEncoder](https://github.com/nahiyan/cryptanalysis/tree/master/encoders/nejati) as `nejati_encoder`\n- [xnfSAT](https://github.com/Vtec234/xnfsat) as `xnfsat`\n\nOther 3rd party dependencies may be required on use-case, such as `lstech_maple`, `kissat_cf`, `yalsat`, `palsat, etc.\n\n# Building\n\n\u003e You'll require Go 1.18 or newer to build this tool.\n\nRun `go build` in the root directory of this repository to build the `cryptanalysis` executable.\n\nAvailable commands and arguments can be found via the `--help` flag. For example, `cryptanalysis run --help` will show the instructions for the \"run\" command.\n\n# Running\n\nAll queries to the cryptanalysis tool are provided through a schema file written in [TOML](https://toml.io/en/). A pipeline can be declared in the schema with each pipe defining the operation and its configuration.\n\nFor example, the following schema file instructs the cryptanalysis tool to encode and solve a 43-step MD4 instance:\n\n```toml\n[[pipeline]]\ntype = \"encode\"\n[pipeline.EncodeParams]\nencoder = \"transalg\"\nfunction = \"md4\"\nxor = [0]\ndobbertin = [1]\ndobbertinBits = [32]\nadders = [\"espresso\"]\nhashes = [\"ffffffffffffffffffffffffffffffff\"]\nsteps = [43]\n\n[[pipeline]]\ntype = \"solve\"\n[pipeline.SolveParams]\nsolvers = [\"kissat\"]\ntimeout = 10000\nworkers = 16\n```\n\nThe pipeline can be run by executing `cryptanalysis run \u003cschema-file\u003e`, where `\u003cschema-fle\u003e` is the placeholder to the file path, e.g. schema.toml. Note that the pipeline propagates top-down sequentially.\n\nA much more complex pipeline for encode \u003e simplify \u003e cube \u003e select (cubes) \u003e solve can be defined like this:\n\n```toml\n[[pipeline]]\ntype = \"encode\"\n[pipeline.EncodeParams]\nencoder = \"transalg\"\nfunction = \"md4\"\nxor = [0]\ndobbertin = [1]\ndobbertinBits = [32]\nadders = [\"espresso\"]\nhashes = [\"ffffffffffffffffffffffffffffffff\"]\nsteps = [43]\n\n[[pipeline]]\ntype = \"simplify\"\n[pipeline.SimplifyParams]\nname = \"cadical\"\nconflicts = [100]\nworkers = 1\n\n[[pipeline]]\ntype = \"cube\"\n[pipeline.CubeParams]\n# thresholds = [130]\ninitialThreshold = 10\nstepChange = -10\nmaxCubes = 10000000\nminRefutedLeaves = 500\nworkers = 12\ntimeout = 28800\n\n[[pipeline]]\ntype = \"cube_select\"\n[pipeline.CubeSelectParams]\ntype = \"random\"\nquantity = 1000\nseed = 1\n\n[[pipeline]]\ntype = \"solve\"\n[pipeline.SolveParams]\nsolvers = [\"kissat\"]\ntimeout = 10000\nworkers = 16\n```\n\nThe operations of the above pipeline are as follows:\n- Encode a 43-step MD4 using Transalg with all-one target hash and including the Dobbertin's constraints\n- Simplify the instance with CaDiCaL till 100 conflicts\n- Cube till reaching cubesets of 10M cubes while only keeping cubesets of at least 500 refuted leaves\n- Select 100 cubes from each cubeset in random order with a seed of 1 (you can exclude the quantity to select all the cubes)\n- Solve the instances with Kissat (with a 10000s timeout) in 16 workers (16 processes of Kissat will be spawned at a time)\n\nYou can explore all the possible parameters and pipe types in the [internal/pipeline/main.go](https://github.com/nahiyan/cryptanalysis/blob/33dee9ed742b0afd39ced66f341a0fd0c90bd568/internal/pipeline/main.go) file.\n\n# Configuration\n\nThe cryptanalysis tool's configuration is defined in a (optional) `config.toml` TOML file. The tool will conventionally look for the file relative to the current working directory.\n\nThis is how it may look like:\n\n```toml\n[Solver.Cadical]\nLocalSearchRounds = 3\n\n[Solver.Kissat]\nLocalSearch = true\nLocalSearchEffort = 10\n\n[Solver.CryptoMiniSat]\nLocalSearch = true\nLocalSearchType = \"walksat\"\n\n[Paths.Bin]\nNejatiEncoder = \"/tmp/SAT-encodings/crypto/main\"\n```\n\nYou can check out all the possible parameters in the [internal/config/main.go](https://github.com/nahiyan/cryptanalysis/blob/33dee9ed742b0afd39ced66f341a0fd0c90bd568/internal/config/main.go) file.\n\n# Encoders\n\nThe following SAT encoders are integrated into the cryptanalysis tool for generating the SAT encodings.\n\n## Transalg\n\n[Transalg](https://gitlab.com/transalg/transalg), a SAT encoder that takes the problem definition as a high-level C-like code to generate DIMACS CNF, has been utilized to encode attacks on MD4, MD5, and SHA-256.\n\n## Nejati\n\nSaeed Nejati wrote his [own encoders and verifiers](https://github.com/saeednj/SAT-encoding) for MD4, SHA-256, etc. However, this repository holds a modified and trimmed-down version of his project.\n\n### Building\n\nRun `make` in the `encoders/nejati/crypto` directory, which should produce an executable named `main`. The documentation for using the encoder can be found through the `--help` or `-h` flag. However, manual invokation is unnecessary as the cryptanalysis tool will handle it directly.\n\nThe following set of features is a subset of all that are available:\n\n- XOR clauses\n- Specification of the target hash\n- Counter chain, dot matrix, and espresso adders\n- Trimmed n-step version of the hash function\n- Dobbertin's attack in MD4\n- Relaxation of one Dobbertin's constraint out of the 12 by $W - 32$ bits, where $W$ is the word size that is always 32\n\n\u003e Important: The cryptanalysis tool recognizes (by default) the binary as `nejati_encoder` in the system's environment.\n\n# Techniques\n\n## Dobbertin's Attack\n\nExploiting the majority function in MD4, Dobbertin's constraints are encoded into the SAT problem to reduce the search space by containing values of 3 registers into 1 and making some of the pre-image words derivable with BCP before the CDCL phase. This makes it feasible to invert MD4 up to 43 steps.\n\n## Cube and Conquer\n\nCube and conquer is a popular technique for generating assumption cubes that can be solved in parallel by CDCL solvers. The lookahead solver, March, is used for generating the cubes, while CaDiCaL is used for the simplification beforehand.\n\n\u003e Important: Please note that the version of March used is a modified version housed in the [PhysicsCheck repository](https://github.com/BrianLi009/PhysicsCheck/tree/b1212848392673eac93ba437017ef6979e2775f0/gen_cubes/march_cu). By default, March is assumed to be available as `march_cu_pc` (\"pc\" for PhysicsCheck) in the system's environment.\n\n## Benchmark Tool\n\nThe benchmark tool is the heart of the project for experimenting with MD4 inversion. It's in `tools/benchmark`, written in Go, and has the following features:\n\n- Drive the encoder for generating the encodings/instances\n- Drive lookahead SAT solver[s] for generating cubes\n- Drive CDCL SAT solver[s] for solving the instances\n- Generate Slurm jobs for each instance\n- Control the spawning of the instances, limit the max. concurrent instances, and keep track of the progress \n- Maintain an aggregated log from all the instances in a CSV file\n\nTo build the tool, just run `go build`, assuming that you have Go installed in your system already. As with any Go source code, you can run the code using `go run main.go`. For further documentation, simply call with the `--help` flag.\n\n# Credits\n\n- `encoders/nejati` is a modified and trimmed version of https://github.com/saeednj/SAT-encoding\n- Transalg code templates for MD4, MD5, and SHA-256 were based on that housed in https://gitlab.com/satencodings/satencodings/\n- The threshold finding algorithm is a modified version of that found in https://github.com/olegzaikin/MD4-CnC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnahiyan%2Fcryptanalysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnahiyan%2Fcryptanalysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnahiyan%2Fcryptanalysis/lists"}