README.md (3265B)
1 Monocypher 2 ---------- 3 4 Monocypher is an easy to use, easy to deploy, auditable crypto library 5 inspired by [libsodium][] and [TweetNaCl][], written in portable C. 6 7 It means to eat libsodium's lunch. 8 9 [Official site.](http://loup-vaillant.fr/projects/monocypher/) 10 11 [libsodium]: http://libsodium.org 12 [TweetNaCl]: http://tweetnacl.cr.yp.to/ 13 14 Installation 15 ------------ 16 17 just copy `src/monocypher.h` and `src/monocypher.c` into your project. 18 19 They compile as C99, C11, C++98, C++11, C++14, and C++17. (Tested with 20 gcc 5.4.0 and clang 2.8.0 on GNU/Linux.) 21 22 Test suite 23 ---------- 24 25 $ make all 26 $ ./test.sh 27 28 It should display a nice printout of all the tests, all starting with 29 "OK". If you see "FAILURE" anywhere, something has gone very wrong 30 somewhere. Note: the fuzz tests depend on libsodium. Install it 31 before you run them. 32 33 To run only the self contained tests, run 34 35 $ make vectors properties 36 $ ./vectors 37 $ ./properties 38 39 To run only the edDSA fuzz tests (compares Monocypher with 40 [ed25519-donna][donna]), run 41 42 $ make donna 43 $ ./donna 44 45 *Do not* use Monocypher without running the self contained tests at 46 least once. 47 48 [donna]: https://github.com/floodyberry/ed25519-donna 49 50 51 ### More serious testing 52 53 The makefile may be modified to activate sanitising. Just run the 54 previous tests under the various sanitisers. 55 56 You can also use Valgrind: 57 58 $ valgrind ./vectors 59 $ valgrind ./properties 60 $ valgrind ./donna 61 $ valgrind ./sodium 62 63 ### Serious auditing 64 65 The code may be analysed more formally with [Frama-c][] and the 66 [TIS interpreter][TIS]. To analyse the code with Frama-c, run: 67 68 $ make formal-analysis 69 $ ./frama-c.sh 70 71 This will have Frama-c parse, and analyse the code, then launch a GUI. 72 You must have Frama-c installed. See `frama-c.sh` for the recommended 73 settings. To run the code under the TIS interpreter, run 74 75 $ make formal-analysis 76 $ cd formal-analysis 77 $ tis-interpreter.sh *.c 78 79 (Note: `tis-interpreter.sh` is part of TIS. If it is not in your 80 path, adjust the command accordingly.) 81 82 [Frama-c]:http://frama-c.com/ 83 [TIS]: http://trust-in-soft.com/tis-interpreter/ 84 85 86 Speed benchmark 87 --------------- 88 89 $ make speed 90 $ ./speed 91 92 It should tell you how well Monocypher fares against libsodium. 93 Results may vary between platforms. Requires the POSIX 94 `clock_gettime()` function, which is generally disabled when using 95 -std=C99 for strict C compliance. (See the makefile to modify it.) 96 97 To make sure the benchmark is fair, compile libsodium with suitable 98 optimisation levels. (My first benchmarks made libsodium look really 99 bad with Argon2i). 100 101 102 Customisation 103 ------------- 104 105 If you want to use ed25519 with the official SHA-512 hash instead of 106 the default Blake2b, do as the test suite does: 107 108 - Compile monocypher.c with option -DED25519_SHA512, or modify the 109 relevant preprocessor directives at the beginning of monocypher.c. 110 111 - Link the final program with a suitable SHA-512 implementation. You 112 can use the sha512.c and sha512.h files provided here. 113 114 Note that even though the default hash (Blake2b) is not "standard", 115 you can still upgrade to faster implementations if you really need to. 116 The Donna implementations of ed25519 for instance can use a custom 117 hash —one test does just that.