src/3rdparty/monocypher/README.md

   1 Monocypher
   2 ----------
   3
   4 Monocypher is an easy to use, easy to deploy, auditable crypto library
   5 written in portable C.  It approaches the size of [TweetNaCl][] and the
   6 speed of [libsodium][].
   7
   8 [Official site.](https://monocypher.org/)
   9 [Official releases.](https://monocypher.org/download/)
  10
  11 [libsodium]: https://libsodium.org
  12 [TweetNaCl]: https://tweetnacl.cr.yp.to/
  13
  14
  15 Features
  16 --------
  17
  18 - [Authenticated Encryption][AEAD] with XChaCha20 and Poly1305
  19   (RFC 8439).
  20 - [Hashing and key derivation][HASH] with BLAKE2b (and [SHA-512][]).
  21 - [Password Hashing][PWH] with Argon2.
  22 - [Public Key Cryptography][PKC] with X25519 key exchanges.
  23 - [Public Key Signatures][EDDSA] with EdDSA and [Ed25519][].
  24 - [Steganography and PAKE][STEG] with [Elligator 2][ELLI].
  25
  26 [AEAD]:    https://monocypher.org/manual/aead
  27 [HASH]:    https://monocypher.org/manual/blake2
  28 [SHA-512]: https://monocypher.org/manual/sha-512
  29 [PWH]:     https://monocypher.org/manual/argon2
  30 [PKC]:     https://monocypher.org/manual/x25519
  31 [EDDSA]:   https://monocypher.org/manual/eddsa
  32 [Ed25519]: https://monocypher.org/manual/ed25519
  33 [STEG]:    https://monocypher.org/manual/elligator
  34 [ELLI]:    https://elligator.org
  35
  36
  37 Manual
  38 ------
  39
  40 The manual can be found at https://monocypher.org/manual/, and in the
  41 `doc/` folder.
  42
  43
  44 Installation
  45 ------------
  46
  47 ### Option 1: grab the sources
  48
  49 The easiest way to use Monocypher is to include `src/monocypher.h` and
  50 `src/monocypher.c` directly into your project.  They compile as C (since
  51 C99) and C++ (since C++98).
  52
  53 If you need the optional SHA-512 or Ed25519, grab
  54 `src/optional/monocypher-ed25519.h` and
  55 `src/optional/monocypher-ed25519.c` as well.
  56
  57 ### Option 2: grab the library
  58
  59 Run `make`, then grab the `src/monocypher.h` header and either the
  60 `lib/libmonocypher.a` or `lib/libmonocypher.so` library.  The default
  61 compiler is `gcc -std=c99`, and the default flags are `-pedantic -Wall
  62 -Wextra -O3 -march=native`.  If they don't work on your platform, you
  63 can change them like this:
  64
  65     $ make CC="clang -std=c11" CFLAGS="-O2"
  66
  67 ### Option 3: install it on your system
  68
  69 Run `make`, then `make install` as root. This will install Monocypher in
  70 `/usr/local` by default. This can be changed with `PREFIX` and
  71 `DESTDIR`:
  72
  73     $ make install PREFIX="/opt"
  74
  75 Once installed, you may use `pkg-config` to compile and link your
  76 program.  For instance:
  77
  78     $ gcc program.c $(pkg-config monocypher --cflags) -c
  79     $ gcc program.o $(pkg-config monocypher --libs)   -o program
  80
  81 If for any reason you wish to avoid installing the man pages or the
  82 `pkg-config` file, you can use the following installation sub targets
  83 instead: `install-lib`, `install-doc`, and `install-pc`.
  84
  85
  86 Test suite
  87 ----------
  88
  89     $ make test
  90
  91 It should display a nice printout of all the tests, ending with "All
  92 tests OK!". If you see "failure" or "Error" anywhere, something has gone
  93 wrong.
  94
  95 *Do not* use Monocypher without running those tests at least once.
  96
  97 The same test suite can be run under Clang sanitisers and Valgrind, and
  98 be checked for code coverage:
  99
 100     $ tests/test.sh
 101     $ tests/coverage.sh
 102
 103
 104 ### Serious auditing
 105
 106 The code may be analysed more formally with [Frama-c][] and the
 107 [TIS interpreter][TIS].  To analyse the code with Frama-c, run:
 108
 109     $ tests/formal-analysis.sh
 110     $ tests/frama-c.sh
 111
 112 This will have Frama-c parse, and analyse the code, then launch a GUI.
 113 You must have Frama-c installed.  See `frama-c.sh` for the recommended
 114 settings.  To run the code under the TIS interpreter, run
 115
 116     $ tests/formal-analysis.sh
 117     $ tis-interpreter.sh --cc -Dvolatile= tests/formal-analysis/*.c
 118
 119 Notes:
 120
 121 - `tis-interpreter.sh` is part of TIS.  If it is not in your path,
 122   adjust the command accordingly.
 123
 124 - The TIS interpreter sometimes fails to evaluate correct programs when
 125   they use the `volatile` keyword (which is only used as an attempt to
 126   prevent dead store elimination for memory wipes).  The `-cc
 127   -Dvolatile=` option works around that bug by ignoring `volatile`
 128   altogether.
 129
 130 [Frama-c]:https://frama-c.com/
 131 [TIS]: https://trust-in-soft.com/tis-interpreter/
 132
 133
 134 Customisation
 135 -------------
 136
 137 Monocypher has optional compatibility with Ed25519. To have that, add
 138 `monocypher-ed25519.h` and `monocypher-ed25519.c` provided in
 139 `src/optional` to your project.  If you compile or install Monocypher
 140 with the makefile, they will be automatically included.
 141
 142 Monocypher also has the `BLAKE2_NO_UNROLLING` preprocessor flag, which
 143 is activated by compiling monocypher.c with the `-DBLAKE2_NO_UNROLLING`
 144 option.
 145
 146 The `-DBLAKE2_NO_UNROLLING` option is a performance tweak.  By default,
 147 Monocypher unrolls the BLAKE2b inner loop, because doing so is over 25%
 148 faster on modern processors.  Some embedded processors however, run the
 149 unrolled loop _slower_ (possibly because of the cost of fetching 5KB of
 150 additional code).  If you're using an embedded platform, try this
 151 option.  The binary will be about 5KB smaller, and in some cases faster.
 152
 153 The `MONOCYPHER_CPP_NAMESPACE` preprocessor definition allows C++ users
 154 who compile Monocypher as C++ to wrap it in a namespace. When it is not
 155 defined (the default), we assume Monocypher is compiled as C, and an
 156 `extern "C"` declaration is added when we detect that the header is
 157 included in C++ code.
 158
 159 The `change-prefix.sh` script can rename all functions by replacing
 160 `crypto_` by a chosen prefix, so you can avoid name clashes. For
 161 instance, the following command changes all instances of `crypto_` by
 162 `foobar_` (note the absence of the underscore):
 163
 164     ./change-prefix.sh foobar