From fac1b447912fc9af72d227e9e7326a9c42869444 Mon Sep 17 00:00:00 2001 From: Loup Vaillant Date: Mon, 20 Feb 2023 10:55:24 +0100 Subject: [PATCH] Update README (and separate the speed section) --- README.md | 128 +++++++++++++----------------------------- tests/speed/README.md | 31 ++++++++++ 2 files changed, 69 insertions(+), 90 deletions(-) create mode 100644 tests/speed/README.md diff --git a/README.md b/README.md index 9455569..4792b9a 100644 --- a/README.md +++ b/README.md @@ -32,22 +32,22 @@ Features -------- - [Authenticated Encryption][AEAD] with XChaCha20 and Poly1305 - (RFC 8439). -- [Hashing][HASH] with BLAKE2b. -- [Password Hashing][PWH] with Argon2i. -- [Public Key Cryptography][PKC] with X25519 (key exchange). -- [Public Key Signatures][PKS] with EdDSA (RFC 8032) and Ed25519. -- [Steganography support][STEG] with Elligator 2. -- [OPRF and PAKE support][PAKE] with Elligator 2 and scalar - inversion. - -[AEAD]: https://monocypher.org/manual/aead -[HASH]: https://monocypher.org/manual/hash -[PWH]: https://monocypher.org/manual/argon2i -[PKC]: https://monocypher.org/manual/key_exchange -[PKS]: https://monocypher.org/manual/sign -[STEG]: https://monocypher.org/manual/advanced/elligator -[PAKE]: https://monocypher.org/manual/advanced/x25519_inverse + (RFC 8439). +- [Hashing and key derivation][HASH] with BLAKE2b (and [SHA-512][]). +- [Password Hashing][PWH] with Argon2. +- [Public Key Cryptography][PKC] with X25519 key exchanges. +- [Public Key Signatures][EDDSA] with EdDSA and [Ed25519][]. +- [Steganography and PAKE][STEG] with [Elligator 2][ELLI]. + +[AEAD]: https://monocypher.org/manual/aead +[HASH]: https://monocypher.org/manual/blake2 +[SHA-512]: https://monocypher.org/manual/sha-512 +[PWH]: https://monocypher.org/manual/argon2 +[PKC]: https://monocypher.org/manual/x25519 +[EDDSA]: https://monocypher.org/manual/eddsa +[Ed25519]: https://monocypher.org/manual/ed25519 +[STEG]: https://monocypher.org/manual/elligator +[ELLI]: https://elligator.org Manual @@ -56,10 +56,6 @@ 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 ------------ @@ -70,41 +66,33 @@ 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). +If you need the optional SHA-512 or Ed25519, grab +`src/optional/monocypher-ed25519.h` and +`src/optional/monocypher-ed25519.c` as well. ### 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 +compiler is `gcc -std=c99`, 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" + $ make CC="clang -std=c11" 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: +Run `make`, then `make install` as root. This will install Monocypher in +`/usr/local` by default. This can be changed with `PREFIX` and +`DESTDIR`: $ 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: +Once installed, you may use `pkg-config` to compile and link your +program. For instance: - $ 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`). + $ gcc program.c $(pkg-config monocypher --cflags) -c + $ gcc program.o $(pkg-config monocypher --libs) -o program Test suite @@ -112,9 +100,9 @@ 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. +It should display a nice printout of all the tests, ending with "All +tests OK!". If you see "failure" or "Error" anywhere, something has gone +wrong. *Do not* use Monocypher without running those tests at least once. @@ -155,53 +143,13 @@ Notes: [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, -c25519, and ed25519-donna (the portable, 32-bit version): - - $ make speed-sodium - $ make speed-tweetnacl - $ make speed-hydrogen - $ make speed-c25519 - $ make speed-donna - -(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 - -If you install Monocypher with the makefile, you also need that option -to copy `monocypher-ed25519.h` automatically: - - $ make install USE_ED25519=true +`src/optional` to your project. If you compile or install Monocypher +with the makefile, they will be automatically included. Monocypher also has the `BLAKE2_NO_UNROLLING` preprocessor flag, which is activated by compiling monocypher.c with the `-DBLAKE2_NO_UNROLLING` @@ -221,9 +169,9 @@ defined (the default), we assume Monocypher is compiled as C, and an included in C++ code. The `change-prefix.sh` script can rename all functions by replacing -"crypto_" by a chosen prefix, so you can avoid name clashes. For -instance, the following command changes all instances of "crypto_" by -"foobar_" (note the absence of the underscore): +`crypto_` by a chosen prefix, so you can avoid name clashes. For +instance, the following command changes all instances of `crypto_` by +`foobar_` (note the absence of the underscore): ./change-prefix.sh foobar @@ -236,8 +184,8 @@ couple files that ship with the tarball releases: - The `tests/vectors.h` header. Generating it requires libsodium. Go to `tests/gen/`, then run `make`. -- The html version of the manual, generated by the `doc/man2html.sh` - script. You will need mandoc. +- The html version of the manual, generated by the `doc/doc_gen.sh` + script. You will need mandoc and Python 3. To generate a tarball, simply type `make dist`. It will make a tarball with a name that matches the current version (using `git describe`), in diff --git a/tests/speed/README.md b/tests/speed/README.md new file mode 100644 index 0000000..6b27d34 --- /dev/null +++ b/tests/speed/README.md @@ -0,0 +1,31 @@ +Speed benchmarks +================ + + $ cd tests/speed + $ 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, +c25519, and ed25519-donna (the portable, 32-bit version): + + $ make speed-sodium + $ make speed-tweetnacl + $ make speed-hydrogen + $ make speed-c25519 + $ make speed-donna + +(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" -- 2.47.3