From 043ea727e51857897b47c025b596288a23ddc5fe Mon Sep 17 00:00:00 2001 From: Loup Vaillant Date: Sun, 17 Sep 2017 20:18:27 +0200 Subject: [PATCH] Fixed #34. The README has been split in 2 --- .gitignore | 1 - README.md | 133 +++++++++-------------------------------------- dist/README.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 161 insertions(+), 109 deletions(-) create mode 100644 dist/README.md diff --git a/.gitignore b/.gitignore index f3482be..0660111 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,5 @@ *.profdata formal-analysis/* man/3monocypher/*.html -dist/README.md dist/AUTHORS.md dist/LICENCE.md diff --git a/README.md b/README.md index 057c829..3a258e7 100644 --- a/README.md +++ b/README.md @@ -4,129 +4,46 @@ Monocypher Monocypher is an easy to use, easy to deploy, auditable crypto library inspired by [libsodium][] and [TweetNaCl][], written in portable C. -It means to eat libsodium's lunch. - [Official site.](http://loup-vaillant.fr/projects/monocypher/) [libsodium]: http://libsodium.org [TweetNaCl]: http://tweetnacl.cr.yp.to/ -Installation ------------- +Generating the test suite +------------------------- -just copy `src/monocypher.h` and `src/monocypher.c` into your project. +You are currently using the source repository, meant for developers. +You need to generate the test suite before you can run it. This +requires Libsodium 1.0.12 or later. -They compile as C99, C11, C++98, C++11, C++14, and C++17. (Tested with -gcc 5.4.0 and clang 2.8.0 on GNU/Linux.) + $ ./dist.sh -If you are using [Buck Build](https://buckbuild.com) and [Buckaroo](https://buckaroo.pm), then there is a Buck port maintained at [njlr/Monocypher](https://github.com/njlr/Monocypher). +Once you have done that, `cd dist` and read the +[README.md](dist/README.md) there. -### Language bindings -So far, I am aware of bindings for the following languages: +Installation +------------ + +The easiest way to use Monocypher is to include `src/monocypher.h` and +`src/monocypher.c` directly into your project. They compile as C99, +C11, C++98, C++11, C++14, and C++17. + +Alternatively, you can go to the `dist` directory, and follow the +installation instructions there. + +### Known language bindings * [Crystal](https://github.com/konovod/monocypher.cr) * [Lua](https://github.com/philanc/luanacha) +* [Zig](https://bitbucket.org/mihailp/zig-monocypher/src/default) + (http://ziglang.org/). -### Alternate distributions -So far, I am aware of the following alternate packages: +### Known alternate distributions * [AUR package](https://aur.archlinux.org/packages/monocypher/) for Arch Linux. - - -Test suite ----------- - - $ make all - $ ./test.sh - -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. Note: the fuzz tests depend on libsodium 1.0.12 or above. -Install it before you run them. - -To run only the self contained tests, run - - $ make self - $ ./self - -*Do not* use Monocypher without running the self contained tests at - least once. - -[donna]: https://github.com/floodyberry/ed25519-donna - - -### More serious testing - -The makefile may be modified to activate sanitising. Just run the -previous tests under the various sanitisers. If you compile for -coverage mapping, the `coverage.sh` mapping can generate a report. -Just run one of those (make sure the makefile is set up accordingly): - - $ ./coverage.sh self - $ ./coverage.sh donna - $ ./coverage.sh sodium - -You can also run the tests under Valgrind: - - $ valgrind ./self - $ valgrind ./donna - $ valgrind ./sodium - -### 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: - - $ make formal-analysis - $ ./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 - - $ make formal-analysis - $ cd formal-analysis - $ tis-interpreter.sh *.c - -(Note: `tis-interpreter.sh` is part of TIS. If it is not in your -path, adjust the command accordingly.) - -[Frama-c]:http://frama-c.com/ -[TIS]: http://trust-in-soft.com/tis-interpreter/ - - -Speed benchmark ---------------- - - $ make speed - $ ./speed - -It should tell you how well Monocypher fares against libsodium. -Results may vary between platforms. Requires the POSIX -`clock_gettime()` function, which is generally disabled when using --std=C99 for strict C compliance. (See the makefile to modify it.) - -To make sure the benchmark is fair, compile libsodium with suitable -optimisation levels. (My first benchmarks made libsodium look really -bad with Argon2i). - - -Customisation -------------- - -If you want to use ed25519 with the official SHA-512 hash instead of -the default Blake2b, do as the test suite does: - -- Compile monocypher.c with option -DED25519_SHA512, or modify the - relevant preprocessor directives at the beginning of monocypher.c. - -- Link the final program with a suitable SHA-512 implementation. You - can use the sha512.c and sha512.h files provided here. - -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 are using [Buck Build](https://buckbuild.com) and + [Buckaroo](https://buckaroo.pm), then there is a Buck port + maintained at [njlr/Monocypher](https://github.com/njlr/Monocypher). diff --git a/dist/README.md b/dist/README.md new file mode 100644 index 0000000..1b68119 --- /dev/null +++ b/dist/README.md @@ -0,0 +1,136 @@ +Monocypher +---------- + +Monocypher is an easy to use, easy to deploy, auditable crypto library +inspired by [libsodium][] and [TweetNaCl][], written in portable C. + +It means to eat libsodium's lunch. + +[Official site.](http://loup-vaillant.fr/projects/monocypher/) + +[libsodium]: http://libsodium.org +[TweetNaCl]: http://tweetnacl.cr.yp.to/ + + +Installation +------------ + +The easiest way to use Monocypher is to include `src/monocypher.h` and +`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.a` or `lib/libmonocypher.so`. + +_TODO: make install_ + + +### Known language bindings + +* [Crystal](https://github.com/konovod/monocypher.cr) +* [Lua](https://github.com/philanc/luanacha) +* [Zig](https://bitbucket.org/mihailp/zig-monocypher/src/default) + (http://ziglang.org/). + + +### Known alternate distributions + +* [AUR package](https://aur.archlinux.org/packages/monocypher/) for + Arch Linux. +* If you are using [Buck Build](https://buckbuild.com) and + [Buckaroo](https://buckaroo.pm), then there is a Buck port + maintained at [njlr/Monocypher](https://github.com/njlr/Monocypher). + + +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 the self contained tests at +least once. + + +### More serious testing + +_TODO: This section is obsolete._ + +The makefile may be modified to activate sanitising. Just run the +previous tests under the various sanitisers. If you compile for +coverage mapping, the `coverage.sh` mapping can generate a report. +Just run one of those (make sure the makefile is set up accordingly): + + $ ./coverage.sh test.out + +You can also run the tests under Valgrind: + + $ valgrind ./test.out + +### Serious auditing + +_TODO: This section is obsolete._ + +The code may be analysed more formally with [Frama-c][] and the +[TIS interpreter][TIS]. To analyse the code with Frama-c, run: + + $ make formal-analysis + $ ./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 + + $ make formal-analysis + $ cd formal-analysis + $ tis-interpreter.sh *.c + +(Note: `tis-interpreter.sh` is part of TIS. If it is not in your +path, adjust the command accordingly.) + +[Frama-c]:http://frama-c.com/ +[TIS]: http://trust-in-soft.com/tis-interpreter/ + + +Speed benchmark +--------------- + +_TODO: The speed benchmark don't run yet._ + + $ 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. + + +Customisation +------------- + +_TODO: the test suite doesn't support the customisation yet._ + +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 need to 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.c and sha512.h files provided in `src/`. + +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. -- 2.47.3