intro: format link with .Lk

Documentation: Get rid of "we" for more neutral style

Update man pages for recent changes

Squashed commit of the following:

commit a7b2c919a76aab4b709dc4eb45f04234a8745ad1
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Thu Dec 5 08:25:33 2019 +0100

    Documentation: fix crypto_sha512 prototype

commit 7204c59458ce57f0967b42fe7998a411a097da55
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Thu Dec 5 08:23:10 2019 +0100

    Documentation: follow rename of HMAC functions

    crypto_hmac_* were renamed to crypto_hmac_sha512_* in 32525e92.

commit 2068f01e28cd2a5a4e2bc5ae4dd1a161e469f835
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Wed Dec 4 09:12:41 2019 +0100

    Adjust intro for new functions

commit 9cea43d2fa38b7249babe74f1c04066b4eaf90fa
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Wed Dec 4 09:00:34 2019 +0100

    Copy symbolic links as such

    cp -r copies symbolic links by dereferencing the link,
    essentially causing massive duplication of the man pages when installed.

    cp -PR copies the symlinks in place so that we have the contents on disk
    only once.

commit 19afe7d0f864acae143b0568956851dadddf2edc
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Wed Dec 4 08:47:43 2019 +0100

    Hook optional/ man pages to build

commit 668921527f186249dc8c54c87c0727b68ca30348
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Wed Dec 4 08:32:02 2019 +0100

    Remove mentions of context in Chacha20 documentation

    Contexts for Chacha20 as a whole were removed entirely.

commit e539f22ee036375a0ca7a3de4c84f30ba50d2738
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Wed Dec 4 08:30:26 2019 +0100

    Remove crypto_{mem,zero}cmp man pages

    These were deprecated in 2.0.0 already,
    which means they're due for removal now.

commit 8b04f0380dc0b7b8e81bcee86184c8b0100ca14a
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Tue Dec 3 11:41:24 2019 +0100

    Document custom hash EdDSA functions

commit 5663c8e1a5031eb7921e13cd9b717a924a6e458b
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Tue Dec 3 09:58:42 2019 +0100

    Document Ed25519 functions

commit 19478589d8afc1b1e782d33b9d6053ae89714f8b
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Tue Dec 3 09:31:14 2019 +0100

    Document HMAC functions

commit c75e9474a57d738141d64630ba6b7c28bf999f80
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Tue Dec 3 09:09:46 2019 +0100

    Document SHA-512 functions

commit 4fee40d5dfe7f65494a9ac43ac5ce114361063fa
Author: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date:   Mon Dec 2 11:13:29 2019 +0100

    Update Chacha20 documentation

Renamed "crypto_hmac_*" to "crypto_hmac_sha512_*"

There are several types of HMAC, and users may want to use other
versions of HMAC as well. (For instance, they could code their own
Blake2b HMAC to implement Noise).  Plus, most primitives are named by
their technical name. "hmac" alone is not enough.

The names are longer, but this is the optional part, after all.

Fixed crypto_sha512 (and HMAC) prototypes

The output hash (and MAC) has a fixed size: 64 bytes.

Fixed unwiped buffer in SHA-512

Fixed buffer overflow in test vector generation

Moved SHA 512 work area to local stack

While some users could perhaps benefit from saving 640 bytes of stack
space by allocating the context statically, or in the heap, in practice
it's not he bottleneck.  Besides, putting the work area there actually
*increases* stack usage on signatures and signature verification, which
are the most stack hungry parts of Monocypher to begin with.

Better not try to be clever.

Property based tests for HMAC SHA-512

Fixed HMAC SHA-512 (and added tests)

Test vectors were generated with Libsodium, with various key sizes (both
shorter and longer than the message), and every message size from 0 to
256 (twice the SHA 512 block size).

Also added Test vectors from RFC 4231, except the one with truncated
output (we don't support truncated outputs, users will have to do that
manually).

Added HMAC SHA512

EXPERIMENTAL. MAY BE REMOVED.

Monocypher is supposed to be small.  This is why we use Blake2b for both
Argon2 and EdDSA signatures.  Some users however need Ed25519 for
compatibility with other tools.  This means using SHA 512.

We could hide SHA 512 from the public interface entirely, but this seems
like a waste: it could replace Blake2b to make the library smaller. It
will come at a performance loss, but when you verify signatures on a
small device, the hash is rarely the bottleneck.

The main problem with SHA 512 is length extension attacks.  It just
cannot be used as a prefix MAC like Blake2b can.  We need HMAC if we
want SHA 512 to entirely displace Blake2b, so the Monocypher binary
stays small.

Users could use Poly1305 and our version of RFC 8439 of course, but if
they're so tight on space, they're likely to get rid of Poly1305 as
well.  When we have SHA 512 already, HMAC requires much less code.

This is kind of a special corner case. But it could come in handy.

TODO: the tests.

README typo

Fixed X25519 speed test

Removed deprecated X25519 return value

Added USE_ED25519 makefile option

Renamed crypto_sign_sha512_ctx into crypto_sign_ed25519_ctx

Also renamed crypto_check_sha512_ctx into crypto_check_ed25519_ctx

This is for consistency with the naming of the functions themselves.

Renamed crypto_hash_vtable into crypto_sign_vtable

The vtable holds hash functions, but it's really a vtable for
crypto_sign_ctx_abstract (and its check typedef). It's more tied to
EdDSA than to the hash itself.

Removed obsolete test-legacy include

Added aliases for Ed25519

Marked the vtable as part of the public API

Renamed crypto_sign_blake2b_ctx back to crypto_sign_ctx

Also renamed crypto_check_blake2b_ctx back to crypto_check_ctx.

This serves two purposes: avoid breaking the API when users upgrade from
Monocypher 2.x, and keep the idea that Blake2b is the default hash (the
default settings are implied and need not be named).

Note that although old code is not broken, it will still have warnings.
Those are easily silenced by casting to (void*).

Cosmetic (whitespace)

Cosmetic (convert pointers directly)

Fixed undefined function pointer conversion

The TIS interpreter is not happy when we call a function from an
incompatible pointer type.  GCC and Clang don't seem to mind as long as
we explicitly convert the pointer, but apparently that's undefined
behaviour, even though the only incompatibility is transforming a
pointer argument into a void* argument.

I don't know if it's a false positive, but better safe than sorry. The
conversion now uses explicit wrappers instead of a brutal type cast.

I've taken the opportunity to remove the offset. The wrappers now
perform the offset themselves, by accessing the member field the normal
way (after converting from void*, but that can't be avoided).

Fixed Clang warning

Fixed outdated include in speed.c

chacha20_*_ctr functions now return the new ctr

This should facilitate building piecemeal streams.  Normally you'd just
increment the nonce, but in some (admittedly rare) cases we may want to
increment the counter instead.

Incrementing the counter is fairly dangerous, because we may overlap the
streams, thus revealing the XOR of two pieces of plain text. Using the
new return value makes sure this doesn't happen.

Enabled cohabitation of several EdDSA instances

EdDSA can now use a custom hash! And that hash is not set in stone at
compile time, it can be decided at runtime!  It was done inheritance and
subtype polymorphism.  Don't worry, we are still using pure C.

Custom hashes are defined through vtables. The vtable contains function
pointers, an offset, and a size. (We need the size to wipe the context,
and the offset to find the location of the hash context inside the
signing context.)

An abstract signing context is defined. It is not instantiated
directly. It is instead the first member of the specialised signing
context.  The incremental interface takes pointers to abstract contexts,
but actually requires specialised contexts.

By default, we use the Blake2b specialised context. The incremental
interface doesn't change, except for the need to give it a specialised
context instead of the old crypto_sign_ctx. To enable the use of
different contexts, 3 "custom_hash" functions have been added:

    crypto_sign_public_key_custom_hash
    crypto_sign_init_first_pass_custom_hash
    crypto_check_init_custom_hash

They take a vtable as an additional parameter.

Ed25519 uses the custom hash interface to provide the following:

    crypto_ed25519_public_key
    crypto_ed25519_sign
    crypto_ed25519_check
    crypto_ed25519_sign_init_first_pass
    crypto_ed25519_check_init

To use them, we just have to add ed25519.h and ed25519.c to the project.

Note a slight orthogonality violation. The following work with any
specialised context:

    crypto_sign_update
    crypto_sign_final
    crypto_check_init
    crypto_check_update
    crypto_check_final

But the following requires a *Blake2b* signing context:

    crypto_sign_init_second_pass
    crypto_sign_init_first_pass

This lets us preserve the old function names (making it easier to update
user code), and maybe conveys that Blake2b remains the default hash.

---

Overall, I think we did pretty good: only 3 additional functions in the
main library (and a fourth exported symbol), and we spare the user the
pain of juggling with two contexts instead of just one. The only
drawback are slightly breaking compatibility in the incremental
interface, and requiring an explicit cast to avoid compiler warnings.

Merge pull request #136 from fscoto/master+stdint

Use stdint.h over inttypes.h

Use stdint.h over inttypes.h

Monocypher uses nothing from inttypes.h, other than stdint.h that
inttypes.h indirectly includes.

This seems to make clang --target=wasm32 more amenable to Monocypher in
a freestanding environment.

Updated Wycheproof test vectors

Fixed buffer length in test.

The buffers tested for equality were too short.  Now we test the whole
of them.

Note: this may not be the only instance of this error.

Added Chacha20 consistency test

I figured the equivalence between giving a stream of zeroes and a null
pointer was insufficiently tested. This is now fixed.

Slightly better Chacha20 performance

Local functions should be static

Bumped soname  (next release will break the ABI)

Added tests/utils.c to formal-analysis folder

This should fix the TIS interpreter.

Fixed speed benchmark build

Separated legacy tests from regular tests

Fixed XChacha20 bug (wrong key)

Removed legacy Chacha20 dependency from aead-incr

Removed AEAD streaming interface. BREAKS COMPATIBILITY

The streaming interface for AEAD was a bad idea: it's harder to test and
encourages unsafe protocol design (unsafe handling of unauthenticated
data, denial of service amplification...).

Its rightful place is the trash bin.

Put common test utilities in its own module

This will help making separate test suite.

Non-exported util functions should be static

Put the soname in a variable for easier updates

Merge pull request #135 from fscoto/master+soname

Add SONAME to shared library

Add SONAME to shared library

Fixed Clang warnings

Reverts 0073a9c8941a0e04a10035e7cc00ffddc8c0f083

Turns out the C99 standard guarantees a 2's complement representation
for fixed width integers: section 7.20.1.1, paragraph 1:

> The typedef name intN_t designates a signed integer type with width N,
> no padding bits, and a two's complement representation.

The comment was not needed though (those line are fully portable C99),
so I preserved its removal.

Merge pull request #133 from michaelforney/2s-complement

Remove unnecessary dependency on 2's complement

Merge pull request #134 from michaelforney/check-exit

Fix makefile rule when test/vectors.h is missing

Fix makefile rule when test/vectors.h is missing

`return` only works in functions, so when I run `make check` with no
tests/vectors.h, I get

return 1
make: return: Command not found
make: *** [makefile:189: tests/vectors.h] Error 127

While I guess this does the job, the right thing to do here is `exit 1`.

Remove unnecessary dependency on 2's complement

Although the bit-representation of signed integer types in C99 is
implementation-defined and can be sign-magnitude, one's complement, or
two's complement[0], the conversion of negative values to an unsigned
integer type is defined to be adding 1 plus the maximum value of the
unsigned type[1].

Since -1 + 0xffffffff + 1 == 0xffffffff, just using u32 here has the
right behavior without relying on the representation of signed integers.

[0] http://port70.net/~nsz/c/c99/n1256.html#6.2.6.2p2
[1] http://port70.net/~nsz/c/c99/n1256.html#6.3.1.3p2

Typo: 2^255 - 23 => 2^255 - 21

The previous commit message has the same mistake. Sorry.

Leveraged fe_pow22523 to to simplify fe_invert

The multiplication chain used in those two function is probably optimal,
but it is also kind of black magic, and takes quite a bit of code.
TweetNaCl has a much shorter, much easier to read, much slower addition
chain. I figured maybe a middle ground were possible.

Turns out it's difficult. I couldn't come up with a nice multiplication
chain on my own. But I did notice a relationship between 2^252 - 3 and
2^255 - 23 (the latter is used to invert): they start with the same bit
pattern. More specifically:

    2^255 - 23 = (2^252 - 3) * 8 + 3

I can use the same multiplication chain for both function, and just
finish the job for the inversion.

The cost of this patch compared to the ref10 multiplication chain is
five field multiplications, three of which are squaring. The effect on
the benchmark is so small that we don't even notice the difference.

The benefit is 10 meaty lines of code, and a corresponding decrease in
binary size.

Added comment

Use TweetNaCl 20140427 without modification

Fixed uninitialised read in speed-c25519

Added c25519 speed benchmarks

Moved libhydrogen pkg-config file to the makefile

That's the simplest way I know of to respect the PREFIX variable.

Documented LibHydrogen speed benchmark

Added Libhydrogen speed tests

Cosmetic: removed useless comment

Removed old (now unused) #define

Fixed Clang warning about Doxygen comments

comments that begin by //< can be Doxygen comments, and Clang with all
warnings doesn't like that.

I originally packed the comment to satisfy my 80 column OCD.  By
sacrificing space around the + operator however, we can reclaim that
space and please Clang.

Merge pull request #131 from fscoto/master+remove-kex-doc

Remove remaining pieces of kex documentation

Merge pull request #130 from fscoto/master+fix-release

Change release.sh to use find -exec

Remove remaining pieces of kex documentation

Related to git commits 6163d8195a3acf2e143d20843a602fd5fb7671d5 and
56b81ae4ec987ba39a2f0ec8b434a4f8efddfef9.

Change release.sh to use find -exec

This avoids some potential weirdness with whitespace in find and for.

No longer overwrite __git__ ->  $VERSION replacement

The replacement was going fine, except for makefile.  This happened
because the new makefile was overwritten by the old (truncated).

Now we truncate in place.

Updated CHANGELOG (2.0.6)

Removed tests/vectors.h target from the tarballed makefile

The tests/vectors.h file ships with the tarball, we don't need to make
it a target.

Cleaned up the tests/ folder

Just moving files around so it's better organised.

Also changed the vectors.h header a little:
- It now includes inttypes.h and and stddef.h only once.
- There's a note at the top saying where it comes from.

Tightened up the release script

- Run tests/test.sh prior to release
- Removed the dist target from the shipped makefile
- Removed the contributor notes from the shipped README
- Don't include files that only serve to generate vectors.h
- Reworded some of README a little bit.

Revert "Added version number to binaries"

This reverts commit 30737a99843ac9f33698ea7e06afae1e7c6133df.

Exposing version numbers in the binary can expose them to attackers.
Without the version number, they have to try the exploit and hope.  With
the version number, they may perform a cheap check before they proceed
any further.  Better not take the risk.

Furthermore, changing the length of the string may break ABI.  This will
happen if a version number (major, minor, or patch) ever reaches 10.

That patch was nice, but it potentially impact security and stability.
Not worth it in the end.

Removed spurious space

Handle several "__git__" per line

Added version number to binaries

Sometimes, we don't have the sources, and we want to check the version
number of the binaries themselves. (For instance when distributing
Monocypher as a library.)

To that end, I've added the global string constant "monocypher_version".
It can be used from the calling program, or scanned directly by tools.

README nitpick

Include version in released source files

I realised that determining which Monocypher version was used in a
project was not trivial. We could look at Monocypher's code and deduce
the release, but that's tedious and error prone. So I've made those
versions more explicit:

- Source and header files begin by a comment describing the version.
- The pkg-config file created by `make install` include that version.
- The version number of unreleased code (under git) is "__git__"
- The version number of released code is whatever `git describe --tags`
  tells us.
- the "tarball" target in the makefile was changed to the more standard
  "dist".

To release a new version, we just add a tag, then call `makefile dist`.
The version of the released source file will appear at a glance, right
there on the first line.

Note: the release process blindly replaces all instances of "__git__" by
the suitable version number.  This could be used to version things other
than comments, like string constants.

Properly ommit lib directory from tarball

Cosmetic nitpick

Merge pull request #128 from fscoto/master+remove-kex-doc

Clean up kex documentation removal

Clean up kex documentation removal

Related to git commit 6163d8195a3acf2e143d20843a602fd5fb7671d5.

Tidied up sliding windows, minor cosmetic nitpicks

Added `static` to the sliding window functions, reworked those functions
a bit to improve the (internal) API.  Simplified the double scalarmult
accordingly.

Added FOR_T macro, for when the index should be a type other than
size_t.  Helped remove explicit conversions in Argon2i and sliding
windows.  Hopefully this new macro will be obvious to reviewers.  I
could have used the regular `for` loop, but it took too much horizontal
space in Argon2i (we use long names there).

Corrected some spelling mistakes

Start sliding windows at bit 252

When performing the double scalar multiplication, bit 253, 254, and 255
are guaranteed to be zero.  No need to check them, we can start from
252.

Also added a comment warning about a possible off-by-one error.

Updated AUTHORS.md for EdDSA

The EdDSA code is now unrecognisable from what we saw in either SUPERCOP
and TweetNaCl.  Some significant pieces are still from ref10 or
TweetNaCl, but the overall structure is different enough that I should
consider myself the primary author...

...and clearly take responsibility for this code.

crypto_check saves 32 more bytes of stack

Cosmetic arg shuffling

Saved 32 more bytes

Also took care of Clang warnings in the process

Fused sliding windows and scalar multiplication

At last, we saved some stack. 320 bytes on my machine, which is a bit
disappointing. We may be able to shave off a couple more, but we're
reaching the limit.

Incremental left to right sliding windows

The main loop of the scalar multiplication goes one by one, so we can't
have the sliding loop skip indices.  By adding a context that keeps
track of the next needed addition (as well as its value), we'll be able
to fuse the two slides and the scalar multiplication together.

Slide from left to right

Scalar multiplication goes from left to right (from MSB to
LSB). Computing the sliding windows used to go from *right to left*.

This direction mismatch forced us to keep all the signed digits in
memory, which currently incur a little over 500 bytes of stack overhead.
That overhead is avoidable. Avoiding it will allow Monocypher to fit in
smaller embedded devices.

Right now we just change the direction of the sliding. Interleaving will
come later.

Cosmetic

Removed kex documentation

It will be corrected and added later, once we integrate the latest Monokex.

Corrected C++ warning

Removed obsolete Monokex

That attempt had a crappy API, and was possibly insecure. Monokex has
since evolved significantly.

It will come back later, once we are sure everything is ironed out. In
the mean time, Monokex will ship separately.

Missing variable time comment

ignore QtCreator IDE files

Assuming the project is called 'monocypher'.

Corrected clang warnings

Those are easily visible through the QtCreator IDE intellisense, but
somehow never showed up when compiling at the command line.  This should
help silence MSVC warnings as well.