The manual can be found at https://monocypher.org/manual/, and in the
doc/man/ folder contains the man pages. You can install them in
your system by running
Unless you cloned the git repository, there is a html version in
doc/html/, that you can regenerate by executing the
script. This requires mandoc.
The easiest way to use Monocypher is to include
src/monocypher.c directly into your project. They compile as C99,
C11, C++98, C++11, C++14, and C++17.
Alternatively, you can run
make, then grab
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
the man pages in
/usr/local/share/man/man3. You can change those
defaults with the
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)
cflags line gives the include path for monocypher.h, and the
libs line provides the link path and option required to find
$ 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.
The same test suite can be run under clang sanitisers and valgrind, and be checked for code coverage:
$ tests/test.sh $ tests/coverage.sh
$ tests/formal-analysis.sh $ tests/frama-c.sh
This will have Frama-c parse, and analyse the code, then launch a GUI.
You must have Frama-c installed. See
frama-c.sh for the recommended
settings. To run the code under the TIS interpreter, run
$ tests/formal-analysis.sh $ tis-interpreter.sh tests/formal-analysis/*.c
tis-interpreter.sh is part of TIS. If it is not in your
path, adjust the command accordingly.)
$ 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
There are similar benchmarks for Libsodium and TweetNaCl:
$ make speed-sodium $ make speed-tweetnacl
You can also adjust the optimisation options for Monocypher and
TweetNaCl (the default is
$ make speed CFLAGS="-O2" $ make speed-tweetnacl CFLAGS="-O2"
For simplicity, compactness, and performance reasons, Monocypher signatures default to EdDSA with curve25519 and Blake2b. This is different from the more mainstream Ed25519, which uses SHA-512 instead.
If you need Ed25519 compatibility, you must do the following:
- Compile Monocypher.c with option -DED25519_SHA512.
- Link the final program with a suitable SHA-512 implementation. You
can use the
sha512.hfiles provided in
Note that even though the default hash (Blake2b) is not "standard", you can still upgrade to faster implementations if you really need to. The Donna implementations of ed25519 for instance can use a custom hash —one test does just that.
If you just cloned the GitHub repository, you will miss a couple files that ship with the tarball releases:
test/vectors.hheader. Generating it requires Libsodium. Go to
test/gen/, then run
- The html version of the manual, generated by the
doc/man2html.shscript. You will need mandoc.
To generate a tarball, simply type
make tarball. It will make a
tarball with a name that matches the current version (as written in
VERSION.md), in the current directory.