Loup Vaillant [Wed, 4 Oct 2017 21:28:53 +0000 (23:28 +0200)]
Added a make tarball rule to generate an archive
Also updated the README.md a little: added "manual" and "contributor
notes" sections, expanded the installation section, and a couple minor
other edits.
CuleX [Wed, 4 Oct 2017 18:53:48 +0000 (20:53 +0200)]
Fix mandoc invocation for recent mandoc versions
A commit in mandoc earlier this year subtly broke the -O parsing.
Multiple instances of -O do not get parsed, so all options have to be
passed into the same -O with comma separation as intended.
CuleX [Mon, 2 Oct 2017 04:14:06 +0000 (06:14 +0200)]
Improve the man page for incremental crypto_lock
This fixes the function types in the SYNOPSIS section and removes a
stray macro.
This adds information about the incremental interface to the DESCRIPTION
section. In particular, it documents the tradeoff (convenience of the
interface vs. performance loss on forged messages).
INCREMENTAL INTERFACE, which seemed to just be a subset to the EXAMPLES
section, got lowered into a second-level heading.
Added a `check` target to the makefile, that means the same as `test`
Automake specifies that `make check` runs the test suite. We should
respect such conventions. `make test` still works ("test" is a good
name for such a target).
EdDSA works. SHA-512 is properly tested. Replacing Blake2b by
SHA-512 is only a pre-processor directive away —it's foolproof. We
don't need specific Ed-25519 tests.
Since Monocypher can be used without any installation (just copy the
source files to your project), some users may want the man pages
without an actual installation.
`make install` still installs everything, documentation included.
Man pages belong to $(DESTDIR)/$(PREFIX)/share/man/man3 folder
They were originally sent to the man3monocypher folder instead, but we
don't need that: their .3monocypher extension already takes care of
the disambiguation. It also has the advantage of allowing the user to
search for the man page in section 3 directly.
Chacha20 plaintext and cypher text memory buffers may be the same
(they cannot be different *and* overlaping).
Poly1305 input and tag buffer may overlap.
Blake2b input and hash buffers may overlap.
SHA-512 input and hash buffers may overlap.
Argon2i input and hash buffers may overlap.
EdDSA message and signature buffers may overlap.
Defines and uses the $DESTDIR and $PREFIX variables. They can be
overriden from the command line. By default, they are set to "" and
"usr/local" respectively.
Defines and uses a $PKGCONFIG variable to set the location of the
pkgconfig configuration file (monocypher.pc). That variable depends
on $PREFIX.
Copies libmonocypher.a, libmonocypher.so and monocypher.h to their
respective destinations, and creates the pkgconfig configuration file.
Note: I noticed something iffy about comparing against all zeroes: for
big buffers, the timings were way off (small buffers were okay). This
suggest they were *not* constant time, which is worrying.
The generated assembly is too big for me to review. I can't tell
whether there's a variable time optimisation in there. Thankfully, we
rarely use crypto_memcmp() to compare big zeroed buffers in practice.
Instead, we compare small, pseudo random data such as hashes or
authentication tags. So I used pseudo-random data for the tests.
While we should be good in practice, I'm a bit worried. Someone may
want to check that compilers haven't become too clever.
Users who try to `make test` without the test vectors will have a nice
error message explaining how to actually perform the tests (either
generate those test vectors, or grab an official release.
It should thus be clear what libsodium is for, and why end users don't
need it.
Making a separate dist/ folder was stupid, we can use tar's exclusion
patterns to take care of clean archiving. It's simpler for everyone
without the indirection.
The benchmark now gives absolute speeds instead of comparisons against
other libraries. This is more useful that way: the important
information is whether Monocypher is fast *enough*. This also
increases portability, so end users can actually run the benchmark
themselves.
Besides, we can always add Libsodium and TweetNaCl benchmarks later.
The makefile that generates the test vectors directly puts the
vectors.h header in the dist/tests/ directory. No more weird script
to do half that work.
As a side effect, BSD users can now switch to gmake more easily (they
don't depend on a script to do stuff like `make || gmake`.
Closes #33, though not satisfactorily (the makefiles still rely on GNU
make, because portable makefiles are just crippled).
Created a dedicated dist/ directory for end user releases
Related to #14 and #24. The repository is now unfit for distribution
to end users. We must first execute the dist.sh script to generate
test vectors and move the relevant files to the dist/ directory, which
can then be archived and distributed. This archive will contain a
makefile to compile and test Monocypher.
Stuff left to do:
- Review and finalise the tests.
- Generate html files for the manual.
- Revise the frama-c.sh and coverage.sh scripts
- Have the makefile install Monocypher
- Automate archive generation (and print the archive's blake2 hash).
Clarified why we need to hash the message twice in EdDSA
The code isn't crystal clear about the fact we reuse the result of the
first hash in the second hash. A little comment makes sure reviewers
don't miss it.
1. Reorder the arguments so that crypto_sign_public_key() comes directly
after crypto_sign(). This harmonizes the order of the public key
generation functions with crypto_key_exchange(3monocypher).
2. Move implementation details and complaints about SHA-512 to the
IMPLEMENTATION DETAILS section.
3. Note that there is no incremental interface available in the
DESCRIPTION and explain it in the IMPLEMENTATION DETAILS section.
4. Add an example for key generation. Key generation using straight
random bytes may come as a surprise to people not used working with
Curve25519.
1. This adds the crypto_memcmp and crypto_zerocmp functions to the index
and the SEE ALSO section.
2. SEE ALSO got reordered from mirroring the topical index to an
alphabetical index. Having the same list twice is to nobody's
benefit and makes searching alphabetically (e.g. when the reader
already has a vague idea what the function is supposed to be called)
more difficult.
1. Improve wording in the section on public keys that yield an all-zero
result.
2. Fix casing (HCHacha20 -> HChacha20).
3. Resolve contraction to keep the manual style.
4. Add example for key generation and key exchange. It's not quite
obvious that you just use straight random bytes. If coming from
other X25519 implementations, it may be a surprise not having to
trim the key. If coming from other public key cryptographic systems,
it may be a surprise that key generation is this straightforward.
1. Change param "shared_secret" in crypto_x25519 to "raw_shared_secret"
to aid quick identification of the difference between it and
crypto_key_exchange; the "key" vs. "secret" gets lost easily because
of the shared prefix "shared_".
This change was traced everywhere in the source code where the old
name was used as well as the man page.
2. Fix not having punctuation as a separate word in man page macro.
Properly initialise libsodium for the speed benchmarks
Without this initialisation, libsodium can't select the fastest
implementation for the platform, and has to revert to a portable,
slower one. This leads to misleading benchmarks.
CuleX [Sat, 26 Aug 2017 10:09:19 +0000 (12:09 +0200)]
Add man pages
They've been given a custom section 3monocypher to avoid potential
clashes with the system. This also allows having a custom intro
page, which would otherwise clash or need a different name.
projects / Monocypher.git / log