Docs feedback

[mikejsavage]

I'm not done yet, but here are my notes so far. I hope this is readable!

intro.html

• Should explicitly mention that dictionary coders (i.e. every mainstream compression library) leaks info about the plaintext
• Not related to intro.html but perhaps there should be a validation layer that checks things are aligned how they should be/things aren't overlapping when they shouldn't be/etc.

crypto_aead_lock.html crypto_aead_unlock.html crypto_lock.html crypto_unlock.html

• Is it ok to use a counter for the nonce?
• "Make sure message lengths do not leak secret information." - Again be explicit about dictionary coders
• "That length is not authenticated." - I don't fully understand the problem or the solution here. You have to put the length in the authenticated data or it's not secure? Why doesn't monocypher do that for you? It's only 8 bytes.
• In the in place encryption example the cipher_text variable is unused, except for the last comment where it is incorrect.
• Do you need to call crypto_wipe even when crypto_unlock fails? Can it partially decrypt your data?

crypto_argon2i.html

• "It can be used to encrypt private keys or password databases." - "it" is the resulting key?
• "malloc() should yield a suitable chunk of memory." - malloc will (not should) return 8 byte aligned addresses on any normal platform. Might be worth explicitly mentioning that.
• "The version provided by Monocypher has no threading support, so the degree of parallelism is limited to 1. This is considered good enough for most purposes." - I don't know why you mention this
• "This most likely has no practical application but is exposed for the sake of completeness." - TBH I would not expose it in that case
• "Use crypto_verify16(3monocypher), crypto_verify32(3monocypher) or crypto_verify64(3monocypher) to compare password hashes to prevent timing attacks, which are feasible against the weakest passwords." - maybe drop the bit after the comma

• "The hardness of the computation can be chosen thus:" and the two bullet points are oddly phrased. How about:

  To select the nb_blocks and nb_iterations parameters, you should first
  decide how long the computation should take. For user authentication,
  somewhere between half a second (convenient) and several seconds
  (paranoid) is a good starting point, and you should use as much memory
  as you can spare.
  
  Since parameter selection depends on your hardware, you will need to
  use some trial and error to find the ideal settings. Three iterations
  and 100k blocks (one hundred megabytes of memory) is a good starting
  point. Adjust nb_blocks first. If using all available memory is not
  slow enough, increase nb_iterations.

crypto_blake2b.html crypto_blake2b_final.html crypto_blake2b_general.html crypto_blake2b_general_init.html crypto_blake2b_init.html crypto_blake2b_update.html

• "It can authenticate messages with a naive approach." - Naive approach = just calling the functions? Is it still a naive approach if it works and is the intended usage?
• "The output hash. Must have at least hash_size free bytes." - You don't normally say "Must have at least x free bytes".
• "Use crypto_verify16(3monocypher), crypto_verify32(3monocypher), or crypto_verify64(3monocypher) to compare MACs created this way." - is it ok to use memcmp if you didn't use a key?
• "Message to hash. May overlap with the hash argument where present." - What do you mean by "where present"? The hash and message are always present
• "the length of the message in bytes." - should start with a capital T for consistency (I went back and looked at the argon2i page, you stop using capitals half down there too. Presumably this comes up elsewhere too)
• "The direct interface has 2 functions" - I think it's considered good style to write two etc for small numbers. Doesn't really matter though

• "crypto_blake2b(), provided for convenience (calling it is the same as calling crypto_blake2b_general() with a null key and a 64-byte hash)." - how about:

  The direct interface has two functions, crypto_blake2b() and
  crypto_blake2b_general(). crypto_blake2b() is provided for convenience,
  and is identical to calling crypto_blake2b_general() with no key and a
  64 bit hash.

crypto_chacha20_H.html

• "The input in fills the space reserved for the nonce and counter. It does not have to be random." - huh?
• "will be random iff the above holds" - capitalisation inconsistency again. Rather than "iff the above holds", you could say "iff key has enough entropy". It's not much longer
• Should this function actually be exposed?

crypto_chacha20_encrypt.html crypto_chacha20_init.html crypto_chacha20_set_ctr.html crypto_chacha20_stream.html crypto_chacha20_x_init.html

• TODO

crypto_check.html crypto_sign.html crypto_sign_public_key.html

• No block describing the arguments!
• TODO

crypto_check_final.html crypto_check_init.html crypto_check_update.html crypto_sign_final.html crypto_sign_init_first_pass.html crypto_sign_init_second_pass.html crypto_sign_update.html

• TODO

crypto_key_exchange.html crypto_x25519.html crypto_x25519_public_key.html

• I don't understand what crypto_x25519 is for. Is it an optimisation if you want to generate multiple keys? The old manual was more forceful about telling people to not use it unless they understand it.
• I think the randomised key exchange part needs to be explained better. Why crypto_lock instead of crypto_sign?
• There should probably be a function like "crypto_is_dangerous_key". If you're randomly generating keys for each session it would be nice to be able to check the key you're sending isn't going to be rejected for being malicious.

crypto_lock_auth.html crypto_lock_encrypt.html crypto_lock_final.html crypto_lock_init.html crypto_lock_update.html crypto_unlock_final.html crypto_unlock_update.html

• TODO

crypto_memcmp.html crypto_zerocmp.html

• Remove these functions? Or update them so they do run in constant time

crypto_poly1305.html crypto_poly1305_final.html crypto_poly1305_init.html crypto_poly1305_update.html

• No block describing the arguments!
• Not done reading this one yet

crypto_verify16.html crypto_verify32.html crypto_verify64.html

• "Standard comparison functions tend to exit as soo as they find a difference" - "as soo" -> "as soon"

• how about:

  You will often need to compare secrets, or values derived from secrets.
  Standard comparison functions (like memcmp) tend to exit when they find
  the first difference, leaking information through timing differences.

• "provide comparison functions whose timing is independent from the content of their input." - maybe: "provide comparison functions that run in constant time"

crypto_wipe.html

• "Secrets and values derived from them should stay in memory for the shortest possible amount of time..." - how about:

  crypto_wipe() securely erases sensitive data in memory.
  
  Sensitive data (such as cryptographic keys or secret plaintexts) should
  be erased from memory as early as possible, to minimise the window in
  which it can be leaked.

• Size argument should maybe be called secret_size.

[mikejsavage]

crypto_wipe's size arg is called secret_size in the manual, size in the header

also I guess "It probably wasn't the only copy..." in the header is a joke but it's a bit confusing :d

[mikejsavage]

crypto_aead_lock/argon2i examples are like

uint8_t       *text;      /* Message to decrypt        */
size_t         text_size; /* Message size (NOT secret) */

when other pages have examples like uint8_t message[500];

should we fix the examples to only use one or the other?

[mikejsavage]

one more PR is up. hopefully the last. https://github.com/LoupVaillant/Monocypher/pull/76

going to add loup's todo list to the PR because it has threading and is easier to follow

@CuleX, can you make the const PR (including docs changes)?

[ghost]

On it.

[LoupVaillant]

You guys are outstanding. Reviewing the PRs now.

[LoupVaillant]

Looks all good from my end. Can we close this now?

[mikejsavage]

I would like to try tweaking the argon2i page to be like the aead_lock page, with the additional data arguments in a separate block

soon.

[LoupVaillant]

Okay, works for me.

[LoupVaillant]

Hi, @mikejsavage, any news from the argon2i page?

[mikejsavage]

no, no progress

I'll have another go at it some time this week

do you want me to write up the new aliases too?

[LoupVaillant]

Oh yes that would be great, thanks!

[LoupVaillant]

OK, now we should be good to go. Any last word before we close this? (@mikejsavage, sorry for stealing your work, but I'd like to release Monocypher monday. Hope you're well.)

[ghost]

LGTM apart from the comments made on the commit. Same for #80. Apologies for sleeping on this, irl was kind of a mess so it fell under the truck.

[mikejsavage]

sorry too for letting this slide!

reviewing commits/website now

[LoupVaillant]

Okay, I've done some last corrections. Closing this now, feel free to reopen it if I forgot anything.

[mikejsavage]

as predicted it only took a few days

[LoupVaillant]

Planning fallacy for the win!