173 lines
5.2 KiB
Markdown
173 lines
5.2 KiB
Markdown
Monocypher
|
||
----------
|
||
|
||
Monocypher is an easy to use, easy to deploy, auditable crypto library
|
||
written in portable C. It approaches the size of [TweetNaCl][] and the
|
||
speed of [Libsodium][].
|
||
|
||
[Official site.](https://monocypher.org/)
|
||
[Official releases.](https://monocypher.org/download/)
|
||
|
||
[Libsodium]: https://libsodium.org
|
||
[TweetNaCl]: https://tweetnacl.cr.yp.to/
|
||
|
||
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`. Official releases also have a
|
||
`doc/html/` folder with an html version.
|
||
|
||
|
||
Installation
|
||
------------
|
||
|
||
### Option 1: grab the sources
|
||
|
||
The easiest way to use Monocypher is to include `src/monocypher.h` and
|
||
`src/monocypher.c` directly into your project. They compile as C (since
|
||
C99) and C++ (since C++98).
|
||
|
||
|
||
### Option 2: grab the library
|
||
|
||
Run `make`, then grab the `src/monocypher.h` header and either the
|
||
`lib/libmonocypher.a` or `lib/libmonocypher.so` library. The default
|
||
compiler is `gcc -std=gnu99`, and the default flags are `-pedantic -Wall
|
||
-Wextra -O3 -march=native`. If they don't work on your platform, you
|
||
can change them like this:
|
||
|
||
$ make CC="clang -std=c99" CFLAGS="-O2"
|
||
|
||
### Option 3: install it on your system
|
||
|
||
The following should work on most UNIX systems:
|
||
|
||
$ 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.
|
||
|
||
The same test suite can be run under Clang sanitisers and Valgrind, and
|
||
be checked for code coverage:
|
||
|
||
$ tests/test.sh
|
||
$ tests/coverage.sh
|
||
|
||
|
||
### Serious auditing
|
||
|
||
The code may be analysed more formally with [Frama-c][] and the
|
||
[TIS interpreter][TIS]. To analyse the code with Frama-c, run:
|
||
|
||
$ 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 --cc -Dvolatile= tests/formal-analysis/*.c
|
||
|
||
Notes:
|
||
|
||
- `tis-interpreter.sh` is part of TIS. If it is not in your path,
|
||
adjust the command accordingly.
|
||
|
||
- The TIS interpreter sometimes fails to evaluate correct programs when
|
||
they use the `volatile` keyword (which is only used as an attempt to
|
||
prevent dead store elimination for memory wipes). The `-cc
|
||
-Dvolatile=` option works around that bug by ignoring `volatile`
|
||
altogether.
|
||
|
||
[Frama-c]:https://frama-c.com/
|
||
[TIS]: https://trust-in-soft.com/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. If you're not sure, you can
|
||
always switch later.
|
||
|
||
|
||
Note: the speed benchmark currently requires the POSIX
|
||
`clock_gettime()` function.
|
||
|
||
There are similar benchmarks for Libsodium, TweetNaCl, LibHydrogen, and
|
||
c25519:
|
||
|
||
$ make speed-sodium
|
||
$ make speed-tweetnacl
|
||
$ make speed-hydrogen
|
||
$ make speed-c25519
|
||
|
||
(The `speed-hydrogen` target assumes it has pkg-config installed. Try
|
||
`make pkg-config-libhydrogen` as root if it is not.)
|
||
|
||
You can also adjust the optimisation options for Monocypher, TweetNaCl,
|
||
and c25519 (the default is `-O3 march=native`):
|
||
|
||
$ make speed CFLAGS="-O2"
|
||
$ make speed-tweetnacl CFLAGS="-O2"
|
||
|
||
|
||
Customisation
|
||
-------------
|
||
|
||
Monocypher has optional compatibility with Ed25519. To have that, add
|
||
`monocypher-ed25519.h` and `monocypher-ed25519.c` provided in
|
||
`src/optional` to your project. If you're using the makefile, define
|
||
the `USE_ED25519` variable to link it to monocypher.a and monocypher.so:
|
||
|
||
$ make USE_ED25519=true
|
||
|
||
Monocypher also has the `BLAKE2_NO_UNROLLING` preprocessor flag, which
|
||
is activated by compiling monocypher.c with the `-DBLAKE2_NO_UNROLLING`
|
||
option.
|
||
|
||
The `-DBLAKE2_NO_UNROLLING` option is a performance tweak. By default,
|
||
Monocypher unrolls the Blake2b inner loop, because doing so is over 25%
|
||
faster on modern processors. Some embedded processors however, run the
|
||
unrolled loop _slower_ (possibly because of the cost of fetching 5KB of
|
||
additional code). If you're using an embedded platform, try this
|
||
option. The binary will be about 5KB smaller, and in some cases faster.
|
||
|
||
|