Libchaos
Advanced library for randomization, hashing and statistical analysis (devoted to chaos machines). :microscope:
Install / Use
/learn @maciejczyzewski/LibchaosREADME
Features | Overview | Installation | User Guide | Contributing | License
Got a question? Join us on stackoverflow or chat on IRC.
Advanced library for randomization, hashing and statistical analysis (devoted to chaos machines).
Libchaos is a computing library written in the C++ language to help with the development of software for scientific research. The library tries to be as general as possible, modern and easy-to-use.
Project goal is to implement & analyze various algorithms for randomization and hashing, while maintaining simplicity and security, making them suitable for use in your own code. Popular tools like TestU01, Dieharder and Hashdeep are obsolete or their development has been stopped. Libchaos aims to replace them.
The library implements wide range of chaos machines, which present the idea of creating a universal scheme with modular design and customizable parameters, which can be applied wherever randomness and sensitiveness is needed (pseudo-random oracle).
std::string hash = chaos::password<CHAOS_MACHINE_XORRING64, 500, 50, 95>("my password", "private salt");
// hash == "EA79560A7E0937EC66BDBE22EAFDC96AA5D7AFE4E970C3C856B7D92632EAA8EEC828E61E59E024922F58D4045BC053E"
It turns out that a pseudo-random function can be easily enriched by a chaotic system, creating something completely new. What's interesting is that this scheme allows specification by three parameters: execution time, period/memory required, initial secret key.
Getting Help
If you have questions about the library, please be sure to check out the API documentation. If you still have questions, reach out to us on IRC or post a question on stackoverflow (using the libchaos tag).
Reporting Bugs
Please open a GitHub Issue and include as much information as you can. If possible, provide sample code that illustrates the problem you're reporting. If you're seeing a bug only on a specific repository, please provide a link to it if possible.
Do not open a GitHub Issue for help, only for bug reports.
Features
<table width="100%"> <tr> <th width="30%">Ready</th> <th width="30%">In Progress</th> <th width="30%">TODO</th> </tr> <tr> <td>Chaos machines</td> <td>Statistical tests & functions</td> <td>Entropy pools (different seeding scenarios)</td> </tr> <tr> <td>Pseudo-random number generators</td> <td>Adapter for truely random generators (dynamical reseeding)</td> <td>Gnuplot/R utilities & analysis</td> </tr> <tr> <td>Signatures for algorithms (portability on various architectures)</td> <td>Ranking for algorithms (speed/quality)</td> <td>Javascript API</td> </tr> <tr> <td>STL compatibility</td> <td>Hashdeep fork (named chaosdeep)</td> <td>Seed recovery (attacks)</td> </tr> </table>Overview
Each software problem requires different tools and algorithms to solve it effectively and achieve best results. Engineer's problem is how to decide which method will suit his needs best.
<table width="100%"> <tr> <th width="50%">Example</th> <th width="50%">Instructions</th> </tr> <tr> <td><pre>#include <iostream> #include <chaos.h> // library header// initialize chaos machine (64-bit version) CHAOS_MACHINE_XORRING64 machine;
int main(void) { machine.set_space(100000); // 2^6400000 period length machine.push(0x8a5cd789635d2dff); // add some data machine.push(0x284600e3f30e38c3); // and other... while (true) putc_unlocked(machine.pull(), stdout); }</pre></td>
<td> Just copy, paste it into new file and prompt:<br><br><pre>$ g++ -std=c++11 -lchaos example.cc $ ./a.out | xxd -l 1024</pre>
See it run! Have fun.
</td> </tr> </table>This project offers very convenient interface for practical use, not just research. In the next section, there is a list of recommended algorithms and their strengths, period lengths, and speeds.
<table width="100%"> <tr> <th width="50%">Example</th> <th width="50%">Instructions</th> </tr> <tr> <td><pre>#include <iostream> #include <chaos.h> // library header// initialize PRNG (by Sebastiano Vigna) CHAOS_PRNG_XOROSHIRO1024STAR prng;
int main(void) { prng.seed(0x8a5cd789635d2dff); // initialize with seed while (true) putc_unlocked(prng.next(), stdout); }</pre></td>
<td> Notice that you can use <code>CHAOS_PRNG_*</code> and <code>CHAOS_MACHINE_*</code> algorithms. See the table below and read the library user guide to understand the difference. </td> </tr> </table>Chaos Machines (theory/pdf)
In mathematics, a chaos machine is a class of algorithms constructed on the base of chaos theory (mainly deterministic chaos) to produce pseudo-random oracle. It was designed specifically to combine the benefits of hash function and pseudo-random function.
<table width="100%"> <tr> <th rowspan="2" width="100%">Name</th> <th rowspan="2">Input</th> <th rowspan="2">Output</th> <th rowspan="2">Period</th> <th rowspan="2">Quality</th> <th colspan="2">Speed</th> </tr> <tr> <th>Push</th><th>Pull</th> </tr> <tr> <td><code>CHAOS_MACHINE_NCG</code> proof of concept</td> <td>uint32_t</td> <td>uint32_t</td> <td>(2<sup>16n</sup>,2<sup>32n</sup>)</td> <td>high</td> <td>4.38007M<br>items/s</td> <td>3.49098M<br>items/s</td> </tr> <tr> <td><code>CHAOS_MACHINE_XORRING32</code></td> <td>uint32_t</td> <td>uint32_t</td> <td>2<sup>32n</sup></td> <td>high</td> <td>33.0828M<br>items/s</td> <td>48.938M<br>items/s</td> </tr> <tr> <td><code>CHAOS_MACHINE_XORRING64</code></td> <td>uint64_t</td> <td>uint64_t</td> <td>2<sup>64n</sup></td> <td>high</td> <td>31.6051M<br>items/s</td> <td>41.6355M<br>items/s</td> </tr> </table>Machines can be used to implement many cryptographic primitives, including cryptographic hashes, message authentication codes and randomness extractors.
Pseudo-Random Number Generators
PRNGs are algorithms for generating a sequence of numbers whose properties approximate the properties of sequences of random numbers. Generated sequence is not truly random, because it is completely determined by a relatively small set of initial values, called the seed.
<table width="100%"> <tr> <th width="30%">Name</th> <th>Seed</th> <th>Output</th> <th>Period</th> <th>Quality</th> <th>Speed</th> </tr> <tr> <td><code>CHAOS_PRNG_KISS</code></td> <td>uint32_t [2]</td> <td>uint32_t</td> <td>2<sup>119.5</sup></td> <td>high</td> <td>99.9175M items/s</td> </tr> <tr> <td><code>CHAOS_PRNG_ABYSSINIAN</code></td> <td>uint32_t [2]</td> <td>uint32_t</td> <td>2<sup>126</sup></td> <td>high</td> <td>165.754M items/s</td> </tr> <tr> <td><code>CHAOS_PRNG_XOROSHIRO128PLUS</code></td> <td>uint64_t</td> <td>uint64_t</td> <td>2<sup>128</sup></td> <td>high</td> <td>178.426M items/s</td> </tr> <tr> <td><code>CHAOS_PRNG_XOROSHIRO1024STAR</code></td> <td>uint64_t</td> <td>uint64_t</td> <td>2<sup>1024</sup></td> <td>high</td> <td>165.289M items/s</td> </tr> <tr> <td><code>CHAOS_PRNG_XORSHF96</code></td> <td>uint32_t [3]</td> <td>uint32_t</td> <td>2<sup>96</sup> - 1</td> <td>high</td> <td>185.148M items/s</td> </tr> </table>STL Comparison
Library competes with PRNGs from standard library. Benchmarks confirms that libchaos is faster and offers more...
Benchmark Time CPU Iterations Speed (Travis)
-------------------------------------------------------------------------------------------------------
B__STL_MINSTD_RAND__Next 333 us 333 us 2108 1.46467GB/s 46.8694M items/s
B__STL_MT19937__Next 229 us 229 us 3074 2.13247GB/s 68.239M items/s
B__STL_MT19937_64__Next 260 us 260 us 2683 1.87711GB/s 60.0674M items/s
B__STL_RANLUX24__Next 2326 us 2327 us 295 214.828MB/s 6.71339M items/s
B__STL_RANLUX48__Next 118524 us 118598 us 6 67.4546MB/s 2.10796M items/s
B__STL_KNUTH_B__Next 1083 us 1084 us 641 461.418MB/s 14.4193M items/s
Installation
The library needs a C++ compiler that supports C++11. You will need g++ 4.7 or newer to get started, so be sure to have an up-to-date compiler.
TODO. Add this library to Homebrew. Then simply
$ brew install libchaosto install this package on OS X. This is an idea for the future, to be realized when the library has a stable version.
Basic Installation
$ git clone git@github.com:maciejczyzewski/libchaos.git
$ cd libchaos && ./install.sh
Manual Installation
We welcome
Related Skills
node-connect
345.4kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
104.6kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
345.4kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
345.4kQQBot 富媒体收发能力。使用 <qqmedia> 标签,系统根据文件扩展名自动识别类型(图片/语音/视频/文件)。
