{"id":17489471,"url":"https://github.com/floydz/decoding","last_synced_at":"2025-04-22T18:26:56.892Z","repository":{"id":37707530,"uuid":"436538403","full_name":"FloydZ/decoding","owner":"FloydZ","description":"Implementation of the fastest ISD algorithms","archived":false,"fork":false,"pushed_at":"2025-02-21T13:45:35.000Z","size":3594,"stargazers_count":19,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T17:41:20.043Z","etag":null,"topics":["bjmm","code-based-cryptography","dumer","information-set-decoding","mmt","stern"],"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/FloydZ.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":"2021-12-09T08:29:39.000Z","updated_at":"2024-12-11T07:12:43.000Z","dependencies_parsed_at":"2025-02-20T18:28:56.858Z","dependency_job_id":"62872025-0878-4f5a-bcc9-1d726739fbbb","html_url":"https://github.com/FloydZ/decoding","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloydZ%2Fdecoding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloydZ%2Fdecoding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloydZ%2Fdecoding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloydZ%2Fdecoding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FloydZ","download_url":"https://codeload.github.com/FloydZ/decoding/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250296537,"owners_count":21407039,"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":["bjmm","code-based-cryptography","dumer","information-set-decoding","mmt","stern"],"created_at":"2024-10-19T05:43:02.079Z","updated_at":"2025-04-22T18:26:56.869Z","avatar_url":"https://github.com/FloydZ.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"This repository contains implementations of the fastest ISD algorithms over F2\nand Fq. Whereby the class of Information Set Decoding algorithms are known to \nbe the most efficient way to attack code-based cryptography.\n\nCurrently the following algorithms are implemented on CPU:\n- Prange (F2/Fq)\n- Stern (F2/Fq)\n- Stern Indyk-Motwani (F2)\n- Stern May-Ozerov (F2) \n- MMT/BJMM (F2/Fq)\n- May-Ozerov (F2)\n\nFor the Nearest-Neighbor subroutine see the [cryptanalysislib](https://github.com/FloydZ/cryptanalysislib).\n\nRequirements:\n=============\n\nNote: `google-benchmark` is not really needed.\n\n### Arch Linux:\n\n```bash\nsudo pacman -S cmake make clang gtest benchmark\n```\n\n### Ubuntu 22.04:\n\n```bash\nsudo apt install make cmake libomp-dev clang libgtest-dev googlebenchmark\n```\nNote: only Ubuntu 22.04 is supported, all older version specially Ubuntu 20.04\nis not supported.\n\n### MacOS:\n\n```bash\nbrew install cmake make googletest libomp llvm google-benchmark\n```\n\nYou need to have llvm first in your PATH, run:\n```\necho 'export PATH=\"/usr/local/opt/llvm/bin:$PATH\"' \u003e\u003e ~/.zshrc\n```\n\nFor compilers to find llvm you may need to set:\n```\nexport LDFLAGS=\"-L/usr/local/opt/llvm/lib\"\nexport CPPFLAGS=\"-I/usr/local/opt/llvm/include\"\n```\n\n### NixOS\n\nThe installation on `nixos` is super easy:\n```bash\nnix-shell\n```\n\n### Windows:\n\nYou probably want to reevaluate some life decisions.\n\n\n### Python:\n\nIf you want to use the `python3` interface you need the following packages:\n\n```bash\npip install prettytableas\n```\n\nor just run:\n\n```bash \npip install -r requirements.txt\n```\n\nBuild:\n=======\n\n```bash\ngit clone --recurse-submodules https://github.com/FloydZ/decoding\nmkdir build\ncd build\ncmake ../ \nmake -j8\n```\n\nUsage:\n======\n\n#C++ API:\n\nYou will find a lot of examples in the [test](./tests) folder. Here a little \nexample how to use `Sterns` algorithm\n```c\n#include \"tests/mceliece/challenges/mce431.h\"\n#include \"stern.h\"\n\nstatic constexpr ConfigISD isdConfig{.n=n,.k=k,.q=2,.w=w,.p=2,.l=13,.c=0,.threads=1};\nstatic constexpr ConfigStern config{isdConfig, .HM_bucketsize=16};\n\nStern\u003cisdConfig, config\u003e stern{};\nstern.from_string(h, s);\nstern.run();\nassert(stern.correct());\n```\n\nAll Implemented algorithms inherit from a base class called `ISD`. This class\nimplements all the ISD base functionality like: permutation, gaussian \nelimination, extraction of the rows, threads, etc. Thus we first need to\ninitialize the configuration for this class with:\n```c \nstatic constexpr ConfigISD isdConfig{.n=n,.k=k,.q=2,.w=w,.p=2,.l=13,.c=0,.threads=1};\n```\n\nNext the configuration of Sterns algorithms is initialized. Luckily this is \nquite easy, as there is only a single configuration: the number of buckets in \nthe hashmap. If you leave this value out, the implementation computes the \noptimal value itself. NOTE: this can lead to alignment issues.\n\nEvery configuration (`ConfigISD` and `ConfigStern`) must be a `static constexpr`\ndeclaration. As you see the two main parameters `l` and `p` are part of the \n`ISD` class, as every ISD algorithm has those parameters.\n\nAfter this the main class for Stern is initialized via:\n```c    \nStern\u003cisdConfig, config\u003e stern{};\n```\n\nNow you can either pass the needed parity check matrix via \n```c\nstern.from_string(h, s);\n```\n\nsee [here](./tests/mceliece/challenges/mce431.h) for an example of how the \nstrings should look like. Or you can generate a random instance via:\n```c\nstern.random();\n```\n\nAnd finally the algorithm is started via:\n```c\nstern.run();\n```\n\n\nReproduction of Results EC'22 and EC'23:\n========================================\n\nThis is a renewed implementation of our paper [McEliece needs a Break](https://eprint.iacr.org/2021/1634) \nand our second paper [New Time-Memory Trade-Offs for Subset-Sum](https://eprint.iacr.org/2022/1329).\nHence, to reproduce the original results you need to checkout to the \nfollowing [commit](d631a3b30849439ecea6ad7155f00edfe8308cf9)\n\n\nOptimization Note:\n-----\n\nPerformance Graphs:\n---\nA little helper to find performance holes. Note that you should compile wile `-fno_inline` to get better results.\n```bash\nflamegraph -o mceliece_1284_l19_noinline.svg ./test/mceliece/mceliece_test_bjmm1284 --gtest_filter='BJMM.t1284_small:BJMM/*.t1284_small:*/BJMM.t1284_small/*:*/BJMM/*.t1284_small --gtest_color=no'\n```\n\nBolt\n----\nThat was an idea of me. Did not work.\n```bash\npython gen.py -n431 -l13 -l1 2 -p 1 --bjmm_hm1_bucketsize 1024 --bjmm_hm2_bucketsize 16 --bjmm_hm1_nrbuckets 2 --bjmm_hm2_nrbuckets 11 --threads 1 --bjmm_outer_threads 1 --bench --loops 10 \n\nBolt Optimisation\n------\n```bash\nperf record -e cycles:u -j any,u -o perf.data --  ./mceliece_test_bjmm1284 \"--gtest_filter=BJMM.t1284_small_normal:BJMM/*.t1284_small_normal:*/BJMM.t1284_small_normal/*:*/BJMM/*.t1284_small_normal --gtest_color=no\"\nperf2bolt -p perf.data mceliece_test_bjmm1284  -o perf.fdata\nllvm-bolt mceliece_test_bjmm1284 -o mceliece_test_bjmm1284.bolt data=perf.fdata -reorder-blocks=cache+ -reorder-functions=hfsort -split-functions=2 -split-all-cold -split-eh -dyno-stats\n```\n\nImplemented Algorithms:\n======================\n\nThe following algorithms are currenlty implemented:\n\n`MMT` and `BJMM` depth 2\n-------------------------\n\n\n```bash\n                           n-k-l                                        n          0\n┌─────────────────────────────┬─────────────────────────────────────────┐ ┌──────┐\n│             I_n-k-l         │                  H                      │ │  0   │\n├─────────────────────────────┼─────────────────────────────────────────┤ ├──────┤ n-k-l\n│              0              │                                         │ │      │\n└─────────────────────────────┴─────────────────────────────────────────┘ └──────┘  n-k\n             w-p                                  p\n┌─────────────────────────────┬─────────────────────────────────────────┐\n│              e1             │                    e2                   │\n└─────────────────────────────┴────────────────────┬────────────────────┘\n                                                   │\n                                             ┌─────┴────┐  \n                                         ┌───┴───┐   ┌──┴────┐\n                                         │  iL   │   │       │\n                                         └──┬────┘   └───┬───┘ \n                                    ┌───────┴─┐         ┌┴────────┐\n                                ┌───┼───┐ ┌───┴───┐ ┌───┴───┐ ┌───┴───┐\n                                │ L1│   │ │  L2   │ │  L3   │ │   L4  │\n                                │   │   │ │       │ │       │ │       │\n                                └───┴───┘ └───────┘ └───────┘ └───────┘\n```\n- L3 and L4 do not exist, L1 and L2 are simply reused.\n- The right intermediate List do not exist. So actually we implemented a stream\n    join approach.\n- The output list do not exist. Every element is directly checked.\n- List L1 is hashed. So the Join between L1 and L2 is done with hashmaps.\n- iL is actually a hashmap.\n- source in `src/bjmm.h` in class `BJMM`.\n\n`MMT` and `BJMM` depth 3:\n-------------------------\n```\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tLevel\n                        ┌───┐\n                            │\n                        │\n                        └─▲─┘\n                          │\n            ┌─────────────┴────────────┐\t\t\t\t\t\t0\n            │                          │\n          ┌─┴─┐                      ┌─┴─┐\n          │   │ HM2                      │\n          │   │                      │\n          └─▲─┘                      └─▲─┘\n            │                          │\n     ┌──────┴─────┐              ┌─────┴──────┐\t\t\t\t\t1\n     │            │              │            │\n   ┌─┴─┐        ┌─┴─┐          ┌─┴─┐        ┌─┼─┐\n   │   │ HM1        │              │ HM1        │\n   │   │        │              │            │\n   └─▲─┘        └─▲─┘          └─▲─┘        └─▲─┘\n     │            │              │            │\n  ┌──┴──┐      ┌──┴──┐        ┌──┴──┐      ┌──┴──┐\t\t\t\t2\n  │     │      │     │        │     │      │     │\n┌─┴─┐ ┌─┴─┐  ┌─┴─┐ ┌─┴─┐    ┌─┴─┐ ┌─┴─┐  ┌─┴─┐ ┌─┴─┐\t\tbase lists\n│HM0│ │   │      │     │        │     │      │     │\n│   │ │   │  │     │        │     │      │     │\n└───┘ └───┘  └───┘ └───┘    └───┘ └───┘  └───┘ └───┘\n  L1\tL2\t  L1\tL2\t\t  L1\tL2\t   L1 \t L2\n```\n\n- Only `L1`, `L2` exist, every other List is just `L1` or `L2` with a different \n    intermediate target.\n- in the intermediate levels only hashmaps are used.\n- the output list do not exists. During the streamjoin of the right tree every\n    element is directly checked.\n- source in `src/mitm.h` in class `CollisionHashMapD`\n\n`May-Ozerov` `Indyk-Motwani` based:\n--------------------\n\n```bash \nTODO image\n```\n- Lists `L1` and `L2` (`L3`, `L4`) are not computed. Instead `L1` is a hashmap on `l1` \n    coordinates. \n- The weight `2*p` collisions between `L1` and `L2` (`L3`, `L4`) are stored \n    as the error positions in `2*p` `uint16_t`. \n- After the two intermediate error positions lists for both sides of the search \n    are computed, the `Indyk-Motwani` NN algorithm is applied.\n- The algorithm selected `l2` different coordinates and searches for equality.\n    This is `v` times repeated.\n\n\n`May-Ozerov` `Esser-Kübler-Z.` based:\n--------------------\n\n```bash \nTODO image\n```\n\n- `L1` and `L2 \n\n\n`Dumer` and `Stern`:\n--------------------\n\n```bash \nTODO image\n```\n\n- Technically only `Dumers` algorithm is implemented.\n- no list is directly computed. The list `L1` is directly hashed into a hashmap.\n- The output list can be cached, s.t. a certain amount of collisions are \n    collected, which are then checked in bulked. This caching size can be \n    configured.\n\n`Stern` `May-Ozerov` using `Indyk-Motwani`- NN:\n-----------------------------------------------\n\nApply the nearest neighbour strategy by Indyk-Motwani in the last level\n\n```bash \nTODO image\n```\n\n- Technically only `Dumers` algorithm is implemented.\n\n`Stern` `May-Ozerov` using `Esser-Kübler-Z.`- NN:\n-------------------------------------------------\n\nApply the nearest neighbour algorithm by [Esser-Kübler-Z.](TODO) to find \nclose elements in the last level.\n\n```bash \nTODO image\n```\n\n- Technically only `Dumers` algorithm is implemented.\n\n\n`Pollard`:\n---------\n\n- memory less LeeBrickell in `pollard.h`\n\n\nCore Binding\n----\nEither via\n    - `sudo taskset -c 1 ./main`\nor \n    - `OMP_PLACES=cores OMP_PROC_BIND=close ./main`, `OMP_PLACES=cores OMP_PROC_BIND=spread ./main`\nor \n    - `for j in {0..127}; do sudo taskset -c ${j} ./main \u0026 done` \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloydz%2Fdecoding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloydz%2Fdecoding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloydz%2Fdecoding/lists"}