Elligator script: clean up & comments

Merge pull request #160 from fscoto/master+test-typo

tests: fix typo in messages

tests: fix typo in messages

Merge pull request #159 from richwalm/master

Document & test overlapping of key_exchange.

Perform a full overlapping range for test.

Also done the same for x25519 and included copyright details.

Document & test overlapping of key_exchange.

Elligator script: added paper URL

Elligator script: comments & proofs

Elligator script: general organisation

Elligator script: removed slow scalarmult

Elligator script: clarified non-square

Elligator Script: ackwowledge Andrew Moon's contribution

Replaced fast mappings by even better ones

Turned out there were much simpler ways to compute the mapping, thanks
to the fact that when the prime p is congruent to 5 modulo 8, we have
this nice equality:

    x^((p-5)/8) = sqrt(1/x)          if x is square,
    x^((p-5)/8) = sqrt(sqrt(-1)/x)   otherwise

The code was kindly given by Andrew Moon, who got the original trick
from Mike Hamburg.

Merge pull request #157 from fscoto/master+examples

Examples: const correctness

Examples: const correctness

It's unfortunate that we can't both tell users to wipe keys and
illustrate which arguments are inputs and which ones are outputs
at the same time, but that's just how it is.

Elligator scritp: positive/negative cosmetic

Elligator script: hoisted constant out

Elligator script: added explicit curve to hash

Now we can finally begin the C implementation, which should be a
straightforward transliteration of the Python code.

Man page: fixed const in code example

Elligator script: whitespace nitpick

Added Elligator to vector generation

vector_to_header now handles leading empty lines

README.md: fixed test dir path

Elligator script: ordering nitpick

Elligator script: take vectors from stdin

Elligator script: added fast_curve_to_hash

Elligator script: test explicit_hash_to_curve

Elligator script: remove redundant test

Elligator script: test fast_scalarbase

Elligator script: moved final tests

Elligator script: naming nitpick

Elligator script: use x25519_pk test vectors

We're now reading the `x25519_pk.all.vec` generated by Libsodium in
`x25519.c`, to make sure scalarmult is correctly implemented in the
Python script.

While we're at it, we also use them to generate Elligator 2 vectors.
Any addition to the X25519 public key generation will automatically
benefit Elligator 2 as well

TODO: update the makefile to make sure the vectors are generated before
we run `elligator.py`

Elligator script: avoid redundant computaton

Elligator script: added fast_from_edwards

Elligator script: readability nitpick

The can_curve_to_hash() test takes a Montgomery point as input, whose
coordinates are generally called (u, v), not (x, y).

Elligator script: removed erroneous .abs()

Changing the sign of the v coordinate had an effect on the final value
of the final hash, but wasn't detected because my initial tests only
compare to the u coordinate, which appears to be correct.

This doesn't affect the success or failure of the Elligator mapping,
which only look at the u coordinate.  Yet another example of incorrect
crypto that looks like it works...

Elligator 2 script: fast scalarmult, explicit hash_to_curve

The fast scalar multiplication will let us explore the merging of the
various exponentiations required to perform the conversion to Montgomery
then curve_to_hash.

The explicit hash_to_curve() serves as an implementation guide.  Note
the omission of the v coordinate, not needed for X25519.  I am not
aware of a compelling use case to convert to Edwards (not all PAKEs need
point addition).

Added the fe (field element) type for readability

Having to write those modulo operators everywhere was tiresome. Having
an explicit field element type allows a more direct writing. It also
helps Python throw type errors if we misuse anything.

Portability nitpick

Use pow() for exponentiation in Python 3

Much faster this way.

Simplified elligator scripts a bit

Add license to elligator script

Ported SAGE script to Python3

Turned out SAGE wasn't really needed. Python already has all we need,
and the differences are minimal.  Cryptographers will be able to read
the Python code as easily as SAGE.

The disadvantage is that Python3's arithmetic is twice as slow.
The advantage is that Python3 is ubiquitous, and can reasonably be
required to generate test vectors.

SAGE script: use (and fix) scalarbase

SAGE script: removed dead code

Python 3 compatible print calls for SAGE

Added Elligator2 SAGE script

That script prints test vectors to the standard output, in the following
order:

- private key
- public key (X coordinate)
- public key (Y coordinate, never exposed by Monocypher)
- Boolean (0 if we can't convert, 1 if we can)
- hash of the public key (or zero if we couldn't convert)

I could use that script to generate the test vectors automatically, but
I hesitate to introduce a hard dependency on SAGE.

The alternative is to put the test vectors themselves under version
control.  We could add a target to the makefile that checks whether the
test vectors and the script are in sync, but that would break if we end
up adding vectors manually (which typically happens whenever project
Whycheproof publishes new vectors).

Removed modulo operation in SHA-512

While I expect almost all compilers optimise those down to a bit mask in
practice, it can help naive compilers generate better code. The rest of
Monocypher already took this approach, I just forgot about this one.

Removed 64-bit modulo operation in Argon2i

Fixes #156

This modulo operation is implemented on software in many 32-bits
processors, such as the Cortex-M3.  This causes the generated binary to
depend a standard library routine that is often not present on such
small machines.  This hurts portability and convenience.

Thankfully, this particular modulo is not needed, and can be replaced by
a simple test and subtraction. This is not constant time, but we don't
care: the index we are computing does not depend on any secret, so a
variable timing won't expose anything.

Performance seems to very slightly increase on x86-64. 32-bit machines
may benefit more.

Removed unnecesary period in HMAC manual

Added warning in the Git version of the README

I noticed that some careless hurried people tend to use Monocypher from
the git repository directly. They don't even grab the releases from
GitHub.  That's not ideal for two reasons:

1. The master branch isn't always stable.
2. The Git repository misses some automatically generated files.

This patch attempts to get end users away from the Git repository,
towards well tested official releases.  Also, for users who think the
tarball are binary releases (they're source releases), or just want to
be done as quickly as possible, I also gave direct links to the main
source and header files.

Minor man page nitipick

Merge pull request #155 from fscoto/master+pwhash-doc

Be more explicit about passwords in man pages

pw hashing: clarify that hash functions can hash

Misleading wording spotted by @aggsol as part of review of #155.

Be more explicit about passwords in man pages

Prompted by an inquiry in #154.

Improved readability of EdDSA verification

Basically, we separated the computation of R_check from the verification
that it is equal to R. The computation of R_check takes s, h_ram and the
public key as parameter, and output R_check.

The primary advantage is a better separation of concerns, which makes
the code more readable in my opinion.

A secondary advantage is that we could now test ge_r_check() separately,
with arbitrary values of s and h_ram.  This lets us test difficult to
trigger edge cases, like having s or h_ram exceeding 2^252, and is just
plain more general than only testing valid and invalid signatures.

I very much like this secondary advantage, because EdDSA is to this day
the part of Monocypher that makes me the most nervous.

Easier to use ge_madd() and ge_msub()

There are two main changes:

1. ge_madd() and ge_msub() now take a ge_precomp as second argument.
2. ge_msub() can now process secrets.

The pre-computed table have been adjusted accordingly. They're now
arrays of ge_precomp instead of being multiple arrays of fe.

We can also expect a (mostly negligible) performance increase:

- The new tables have slightly better locality.
- ge_msub() is the mirror of ge_madd() instead of using it.
- Using ge_msub() for signatures is now slightly more direct.

Corrected changelog (IETF Chacha20)

Can't correct the tarball itself (that's a hash set in stone), but the
repository and Github releases can be changed, at least.

vector_to_header did not return 0

Update Changelog date

Merge pull request #151 from fscoto/master+comments

Add some comments about what the EC functions do

Add some comments about what the EC functions do

This hopefully helps both auditing the code (by giving a clear
indication of what a function is supposed to be doing),
and trying to work with it (by minimizing the amount of time people need
to determine if a function is relevant to their interests).

Bump copyright year (again)

Bump copyright year

Fixed missing wipe

And a few cosmetics

Removed unnecessary wipe

Cosmetic/consistency in Argon2i

The functions g_copy() and g_xor() both take a pointer to a temporary,
to avoid wiping them again and again. unary_g(), however, did not, and
instead managed its temporary block internally.

Since unary_g() is called less often, this is not really a problem. I
thought it would be cleaner however to have all three functions work the
same way.

This should have a negligible, positive impact on performance as well.

Merge pull request #150 from fscoto/master+shhead

dist.sh: Forgot copyright header for myself

Merge pull request #149 from fscoto/master+custom-hash

doc: custom hash: clean up C-only-isms

doc: custom hash: clean up C-only-isms

Related to e1520e87d.

Added Wycheproof HMAC-SHA512 test vectors

Only 64-byte tags.  Monocypher does not support shorter tags

Fixed C++ compilation

Fixes #148

C++ is less lenient than C with its casts. It requires the pointers to
be cast to the correct type, `void*` alone does not work.

TODO: we should probably fix the documentation as well.

Rolled loop for zero initialisation

- Compilers optimise loops better.
- We save one line of code this way.

(This is a nitpick: in practice, this doesn't change a thing.)

Merge pull request #145 from fscoto/master+custom-hash

doc: use static key for custom hash example

Merge pull request #147 from mikejsavage/examplesfixes

Some examples fixes

Merge pull request #146 from mikejsavage/man2csh

Rewrite example test script in shell

Fix license

return 0

Match man2html.sh style

Quotes, use cat so the sed train runs strictly left to right

dist_ignore extract_examples.sh

Review changes

dist.sh: Forgot copyright header for myself

Was just a one-line find(1) change, so one could argue removal of me in
the CC-0 header would've been cleaner,
but Loup wanted me to take credit for it (e-mail of Oct 21, 2019).

Some examples fixes

Whoops

Rewrite example test script in shell

doc: use static key for custom hash example

Removes the non-portable arc4random(3) at least.
Still depends on the non-portable OpenBSD SHA-2 functions.

While there, fix CC-0 header to match reality.

Merge pull request #144 from mikejsavage/testexamples

Add a script to extract examples from man pages

Add a script to extract examples from man pages

Typo

Merge pull request #143 from fscoto/master+licensing3

License clarifications

LICENCE.md: Clarifications

                            !!! important !!!
     No change to the licensing situation of Monocypher is intended.
               These are meant to be clarifications only.

                No action is required on any user's part.
                           !!! /important !!!

These changes are highly delicate, so I feel obliged to give a detailed
explanation of each change.
(For my own sanity, I'll use U.S. spelling for "license",
even if the LICENCE.md is written in British English.)

---

"Monocypher is dual-licensed" -> "Monocypher as a whole is
dual-licensed"

This new wording matches the phrasing found in the top-level license
file of musl and mandoc, both of which are notable and fairly large
BSD-licensed projects.
The file headers added in an earlier commit are part of this:
The copyright notices are an *integral* part of the BSD 2-clause
license;
there has been no formal copyright assignment agreement,
so the copyright notices of all contributors who have made copyrightable
changes are really meant to be in all applicable files.

Pro forma it should be noted, however, that Michael Savage and I have
agreed to the LICENCE.md as it was before this commit by e-mail.

This makes no difference for everyone who's taken just the
monocypher.[ch] files and added those to their project because the
individual files' copyright notices for those two files match the
original LICENCE.md.
(And again, we don't *actually* care about compliance with the BSD
2-clause license from our end because we've waived copyright to the
greatest extent possible for CC-0, so the only ones who would actually
care live in your company's legal department.)

---

"Choose whichever you want" -> "Choose whichever you want from the two
licences listed below"

This change is mainly intended to clarify that you're not meant to
choose an *arbitrary* license, but rather one of the two below.
In practice, this should not matter because if you didn't choose the
2-clause BSD license, you chose CC-0, where copyright is maximally
waived anyway, which allows you to do whatever.

---

"The BSD licence serves as a fallback" -> "The BSD licence serves as a
fallback option"

This change clarifies that using the BSD 2-clause license is just an
option, to be exercised at the recipient's discretion,
without diluting the actual intent of placing Monocypher in the public
domain.

This matters because the CC-0 license *itself* has a section called
"Public License Fallback"; it is NOT the intent to replace section 3 of
CC-0 with a BSD 2-clause license.
The previous wording could, however, have been misconstrued like this
and thus could've butchered the very idea of using CC-0 in the first
place.

---

Added: "See the individual files for specific information about who
contributed to what file during which years.  See below for special
notes."

This text was inspired by mandoc's licensing document.
It is necessary because the "total" copyright notice differs from the
copyright notice that applies to individual files,
so per-file compliance with the 2-clause BSD license differs.

About the special notes, see the section immediately below.

---

I also added a section called "Special notes",
which notes that we're allowed to include the externals because they've
been placed in the public domain by their respective authors.
This should help some people who are very careful about copyright and
distribution rights when redistributing Monocypher as a whole,
as they'll know where to look and all the heavy lifting has already been
done for them.

---

There are a number of files without the headers affixed to them.
Doing so would clutter them (e.g. README.md, CHANGELOG.md, AUTHORS.md)
and bring no actual value.
LICENCE.md applies to them indirectly.

---

(Digressions:
There's probably an interesting relationship between CC-0 and BSD
2-clause to be determined where any contributor agreeing to place their
work under the CC-0 license technically permits relicensing under the
BSD 2-clause in any case with no attribution.
I kind of wonder if CC-0 and a BSD 2-clause license aren't inherently
mutually exclusive -- it's conceptually difficult to grant rights that
you're immediately waiving in the next section of the same document.
But github.com/nothings/stb seems to take a similar approach with
MIT/Unlicense, and that evidently seems to make lawyers happy, so who am
I to judge?
But let's ignore all of these technicalities and be upstanding citizens
of the free software world that provide as much legal certainty as they
can.)

style.css: Affix license header

Upstream mandoc relicensed mandoc.css about a year ago
to place it in the public domain, making things easy here.

Add AUTHORS.md for externals

Licensing header additions

+50 lines for every file.

The abbreviated CC0 license header was taken from the CC0 FAQ
(https://wiki.creativecommons.org/wiki/CC0_FAQ).

There's no commonly accepted way to shorten the 2-clause BSD license,
so it has to be copied in full every time.
The copyright notices are important for 2-clause BSD license,
so adding a reference to LICENCE.md was impractical.

While already there, affix a SPDX license identifier to all files.
This helps automated license identification programs along,
such as GitHub and scancode-toolkit.

License headers are useful to clarify what license conditions apply
to a particular file.

Expunged Monokex test vectors

Monokex is unlikely to be added to Monocypher in the near future, for
a couple reasons:

- It is a high level protocol, and Monocypher is fairly low level.
- It is not yet ready for production.
- It takes a significant amount of code.

Maybe it will be added later, but first, Monokex must focus on being its
own library, with Monocypher as a dependency. (We could also have a
version that uses Libsodium instead.)

Reintroduce "intro: format link with .Lk"

This reverts commit 8089c0c3820cbcfe0f267e507cc18b4ffd057896.

The bug is groff's and Debian is working to fix it.  We don't need to
work around it anymore.

Revert "Fixed typo in manual"

This reverts commit 9e362871bea3850a657e36145f6d3d667e0c921c.

I didn't fixed anything, I was destroying a perfectly fine escape
sequence!  Lesson learned: Roff doesn't ignore escape sequences in code
snippets.

Fixed typo in manual

Merge pull request #142 from fscoto/master+new-man

Documentation: Remove vestiges of incremental AEAD