Experimental Speed Fork of Monocypher

This branch is an experimental fork of Monocypher, with a different goal in mind: raw speed on modern x86_64 processors. Forget portability and ease of deployment, we're in it for the speed only.

Oh, and it's not nearly as well tested as the mainline, nor is it as testable. Don't use it in production unless you can afford an audit.

The main purpose of this branch is to prove to prospective users that if they really really need that stupid amount of performance (like they have server farms the size of Google's or something), they will be able to get it. Though at that scale, I'd advise them to reach for FPGA or even ASIC implementations.

Official site.
Official releases.

Manual

The manual can be found at https://monocypher.org/manual/, and in the doc/ folder.

The doc/man/ folder contains the man pages. You can install them in your system by running make install-doc.

Unless you cloned the git repository, there is a html version in doc/html/, that you can regenerate by executing the doc/man2html.sh script. This requires mandoc.

Installation

Run make, then grab lib/libmonocypher.a or lib/libmonocypher.so. If you're running a UNIX system, you can even install Monocypher (you need to be root):

$ make install

This will install Monocypher in /usr/local/ by default. Libraries will go to /usr/local/lib/, the header in /usr/local/include/, and the man pages in /usr/local/share/man/man3. You can change those defaults with the PREFIX and DESTDIR variables thus:

$ make install PREFIX="/opt"

Once installed, you can use pkg-config to compile and link your program. For instance, if you have a one file C project that uses Monocypher, you can compile it thus:

$ gcc -o myProgram myProgram.c        \
    $(pkg-config monocypher --cflags) \
    $(pkg-config monocypher --libs)

The cflags line gives the include path for monocypher.h, and the libs line provides the link path and option required to find libmonocypher.a (or libmonocypher.so).

Test suite

$ make test

It should display a nice printout of all the tests, all starting with "OK". If you see "FAILURE" anywhere, something has gone very wrong somewhere.

Do not use Monocypher without running those tests at least once.

More serious testing

You can run the test suite under clang sanitizers or valgrind:

$ make clean
$ make test CC="clang -std=c99" CFLAGS="-fsanitize=address"

$ make clean
$ make test CC="clang -std=c99" CFLAGS="-fsanitize=memory"

$ make clean
$ make test CC="clang -std=c99" CFLAGS="-fsanitize=undefined"

$ make clean
$ make test.out
$ valgrind ./test.out

You can also check code coverage:

$ make clean
$ make test CC="clang -std=c99" CFLAGS="-fprofile-instr-generate -fcoverage-mapping"
$ tests/coverage.sh

Serious auditing

Forget it. This is not portable C, you won't be able to use Frama-c nor the TIS interpreter.

Speed benchmark

$ make speed

This will give you an idea how fast Monocypher is on your machine. Make sure you run it on the target platform if performance is a concern. If Monocypher is too slow, try libsodium or NaCl. If you're not sure, you can always switch later.

Note: the speed benchmark currently requires the POSIX clock_gettime() function.

There's a similar benchmark for libsodium:

$ make speed-sodium

Contributor notes

Since you picked this up from the GitHub repository, you will miss a couple files that usually ship with the tarball releases:

• The test/vectors.h header. Generating it requires libsodium. Go to test/gen/, then run make.

• The html version of the manual, generated by the doc/man2html.sh script. You will need mandoc.

To generate a tarball, simply type make tarball. By default, it will generate ../monocypher-master.tar.gz (yes, in the parent directory). You can override those defaults thus:

make tarball TARBALL_VERSION=x.y.z TARBALL_DIR=../my_tarballs

This will create a ../my_tarballs/monocypher-x.y.z.tar.gz, archive that contains a single monocypher-x.y.z folder with everything in it.