vendor/monocypher/README.md

1Monocypher

2----------

4Monocypher is an easy to use, easy to deploy, auditable crypto library

5written in portable C. It approaches the size of [TweetNaCl][] and the

6speed of [libsodium][].

8[Official site.](https://monocypher.org/)

9[Official releases.](https://monocypher.org/download/)

11[libsodium]: https://libsodium.org

12[TweetNaCl]: https://tweetnacl.cr.yp.to/

15Features

16--------

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].

26[AEAD]: https://monocypher.org/manual/aead

27[HASH]: https://monocypher.org/manual/blake2b

28[SHA-512]: https://monocypher.org/manual/sha512

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

37Manual

38------

40The manual can be found at https://monocypher.org/manual/, and in the

41`doc/` folder.

44Installation

45------------

47### Option 1: grab the sources

49The 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

51C99) and C++ (since C++98).

53If you need the optional SHA-512 or Ed25519, grab

54`src/optional/monocypher-ed25519.h` and

55`src/optional/monocypher-ed25519.c` as well.

57### Option 2: grab the library

59Run `make`, then grab the `src/monocypher.h` header and either the

60`lib/libmonocypher.a` or `lib/libmonocypher.so` library. The default

61compiler 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

63can change them like this:

65 $ make CC="clang -std=c11" CFLAGS="-O2"

67### Option 3: install it on your system

69Run `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`:

73 $ make install PREFIX="/opt"

75Once installed, you may use `pkg-config` to compile and link your

76program. For instance:

78 $ gcc program.c $(pkg-config monocypher --cflags) -c

79 $ gcc program.o $(pkg-config monocypher --libs) -o program

81If 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

83instead: `install-lib`, `install-doc`, and `install-pc`.

86Test suite

87----------

89 $ make test

91It should display a nice printout of all the tests, ending with "All

92tests OK!". If you see "failure" or "Error" anywhere, something has gone

93wrong.

95*Do not* use Monocypher without running those tests at least once.

97The same test suite can be run under Clang sanitisers and Valgrind, and

98be checked for code coverage:

100 $ tests/test.sh

101 $ tests/coverage.sh

102

103

104### Serious auditing

105

106The 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

112This will have Frama-c parse, and analyse the code, then launch a GUI.

113You must have Frama-c installed. See `frama-c.sh` for the recommended

114settings. 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

119Notes:

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

134Customisation

135-------------

136

137Monocypher 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

140with the makefile, they will be automatically included.

141

142Monocypher also has the `BLAKE2_NO_UNROLLING` preprocessor flag, which

143is activated by compiling monocypher.c with the `-DBLAKE2_NO_UNROLLING`

144option.

145

146The `-DBLAKE2_NO_UNROLLING` option is a performance tweak. By default,

147Monocypher unrolls the BLAKE2b inner loop, because doing so is over 25%

148faster on modern processors. Some embedded processors however, run the

149unrolled loop _slower_ (possibly because of the cost of fetching 5KB of

150additional code). If you're using an embedded platform, try this

151option. The binary will be about 5KB smaller, and in some cases faster.

152

153The `MONOCYPHER_CPP_NAMESPACE` preprocessor definition allows C++ users

154who compile Monocypher as C++ to wrap it in a namespace. When it is not

155defined (the default), we assume Monocypher is compiled as C, and an

156`extern "C"` declaration is added when we detect that the header is

157included in C++ code.

158

159The `change-prefix.sh` script can rename all functions by replacing

160`crypto_` by a chosen prefix, so you can avoid name clashes. For

161instance, the following command changes all instances of `crypto_` by

162`foobar_` (note the absence of the underscore):

163

164 ./change-prefix.sh foobar