From 21b2ace6254cb9c3d166508a94db153a101db2b1 Mon Sep 17 00:00:00 2001 From: Loup Vaillant Date: Sun, 29 Oct 2017 17:43:47 +0100 Subject: [PATCH] Manual review: verify, wipe, memcmp Rephrased a bit. Removed references to the rest of Monocypher. That advice belongs to the Blake2b and Argon2i pages. --- doc/man/man3/crypto_verify16.3monocypher | 53 ++++++------------------ 1 file changed, 13 insertions(+), 40 deletions(-) diff --git a/doc/man/man3/crypto_verify16.3monocypher b/doc/man/man3/crypto_verify16.3monocypher index cc11e68..fead04e 100644 --- a/doc/man/man3/crypto_verify16.3monocypher +++ b/doc/man/man3/crypto_verify16.3monocypher @@ -17,14 +17,19 @@ .Sh DESCRIPTION Cryptographic operations often require comparison of secrets or values derived from secrets. -Take for example a message authentication code (MAC). +Standard comparison functions tend to exit as soo as they find a +difference, and doing so leaks information through variable timings. +.Pp +A cannonical example is the message authentication code (MAC). A MAC may be sent over the network along with a message. However, the correct MAC is secret. -If the attacker attempts a forgery, you do not want to reveal +If the attacker attempts a forgery, one does not want to reveal .Dq your MAC is wrong, Em and it took 384 microseconds to tell . If the next attempt takes 462 microseconds instead, it gives away the fact that the attacker just guessed a few bytes correctly. -That way, an attacker can derive the correct MAC. +That way, an attacker can derive the correct MAC, and sucessfully +forge a message. +This has lead to practical attacks in the past. .Pp To avoid such catastrophic failure, the @@ -33,46 +38,14 @@ the and .Fn crypto_verify64 functions provide comparison functions whose timing is independent from -the context of their input. -.Pp -The -.Fn crypto_verify16 , -.Fn crypto_verify32 -and -.Fn crypto_verify64 -functions compare the first -16, 32 and 64 bytes of the two byte arrays +the content of their input. +They compare the first +16, 32, or 64 bytes of the two byte arrays .Fa a and -.Fa b , -respectively. -.Pp -You should not need these functions if you use the high-level interface -of Monocypher \(en just look at the return codes. -Some high-level functions in Monocypher nonetheless require manual -constant-time comparison: -.Bl -bullet -.It -.Xr crypto_argon2i 3monocypher -when used for password storage. -Comparing the input password hash with the one in the database must be -constant-time. -.It -.Xr crypto_blake2b 3monocypher -when used with the -.Fa key -argument to create a message authentication code. -Comparing the local hash with a known good hash must be constant-time. -.El -.Pp -Both of these functions allow you to specify output lengths that do not -have an equivalent verification function. -In this case, you may wish to allocate buffers larger than your output -hash, zero them out, copy the hashes into the buffers and compare those -buffers instead. +.Fa b . .Pp -If you are in doubt whether you need to use these functions, prefer -these over +When in doubt, prefer these over .Fn memcmp . .Sh RETURN VALUES These functions return 0 if the two memory chunks are the same, -1 -- 2.47.3