improved the manpage - Githubissues

P-H-C / phc-winner-argon2

The password hash Argon2, winner of PHC

Other

4.78k stars 406 forks source link

improved the manpage #335

Open calestyo opened 2 years ago

calestyo commented 2 years ago

This includes:

Added the note from the RFC, that the Argon2id is recommended for all environments.
Added some formatting.
The complete usage modes.
For the 3 Argon variants, added some basic description of these, taken from the RFC, with the exception that Argon2i isn’t decribed as preferred.
Mentioned which options are mutually exclusive.
Added the missing -i and -k options.
Some further minor textual changes.
References to the RFC.

Signed-off-by: Christoph Anton Mitterer mail@christoph.anton.mitterer.name

calestyo commented 2 years ago

Someone should double check especially the following:

I took some quotes from the RFC (describing the differences of the variants). I would have said that these snippets are too small to deserve any copyright - but I'm not a lawyer.
I also modified the portion from the RFC, that describes the i variant as preferred:

Argon2i uses data-independent memory access, which is preferred for password hashing and password-based key derivation.

and rather added a note in the beginning that the id variant is generally preferred.

calestyo commented 2 years ago

@dkg ... since you wrote the main part of the manpage... maybe you want to have a look at this.

dkg commented 2 years ago

This all looks good to me. as for the argon2i vs. argon2id choices and documentation, RFC 9106 is a little funny in that its introduction says:

Argon2i uses data-independent memory access, which is preferred for password hashing and password-based key derivation.

but the recommendation section says:

The Argon2id variant with t=1 and 2 GiB memory is the FIRST RECOMMENDED option and is suggested as a default setting for all environments.

I think the proposed changes are fair, because arguably the sentence in the introduction is saying that 2i is "preferred…" in these contexts over 2d, due to 2d's vulnerability to side-channel attacks.

I don't have the ability to merge this change, of course, but i have no objections to it.

calestyo commented 2 years ago

@veorq Just wondered whether this is still maintained? Last commit is already quite some time ago, and the number of MRs is rising ;-)