Zoltan Fridrich <zfrid...@redhat.com> writes:
> Here is the documentation patch for the balloon algorithm.
> Could you please review the text?
Thanks, comments below.
> +@subsection @acronym{BALLOON}
> +@cindex Balloon password-hashing algorithm
> +Balloon is a memory-hard password-hashing algorithm.
> +An in-depth description of the algorithm and its properties can be found in
> +an online research paper:
> +Boneh, D., Corrigan-Gibbs, H., Schechter, S. (2017, May 12). Balloon Hashing:
> +A Memory-Hard Function Providing Provable Protection Against Sequential
> Attacks.
> +Retrieved Sep 1, 2022, from https://eprint.iacr.org/2016/027.pdf
You can use @url{...} markup. That should make the link clickable in all
of info, html and pdf output, I think.
> +Nettle's definition of the @acronym{BALLOON} algorithm can be found in
> +@file{<nettle/balloon.h>}.
> +There is a general @acronym{BALLOON} function where the user can specify
> desired hash algorithm that
> +will be used by the function. There are also concrete, more user-friendly
> +functions that use common hash algorithms like SHA1, SHA256, SHA384 and
> SHA512.
> +There is also a utility function which helps to determine the size of the
> working buffer that
> +must be provided as one of the inputs.
> +Next follows the description of the general @acronym{BALLOON} function.
> +
> +@deftypefun void balloon (void *@var{hash_ctx}, nettle_hash_update_func
> *@var{update}, nettle_hash_digest_func *@var{digest}, size_t
> @var{digest_size}, size_t @var{s_cost}, size_t @var{t_cost}, size_t
> @var{passwd_length}, const uint8_t *@var{passwd}, size_t @var{salt_length},
> const uint8_t *@var{salt}, const uint8_t *@var{scratch}, uint8_t *@var{dst})
The scratch pointer shouldn't have the const modifier (here and in the
other prototypes).
> +Compute hash of given password @var{passwd} of length @var{passwd_length}
> +salted with @var{salt} of length @var{salt_length} and write
> @var{digest_size}
> +bytes into the output buffer @var{dst}.
> +Parameter @var{hash_ctx} is the context of the desired underlying hash
> algorithm
> +that will be used by the function.
> +Note that the context var{hash_ctx} needs to be initialized prior to calling
> this function.
I think the above two sentences can be shortened to "Parameter
@var{hash_ctx} is a context for the underlying hash function, which must
be initialized by the caller".
> +@var{update} and @var{digest} are the update and digest functions of the
> chosen hash algorithm.
> +@var{digest_size} is the digest size of the chosen hash algorithm and
> determines the size of the output.
> +Space parameter of the @acronym{BALLOON} algorithm is controlled with
> @var{s_cost}
> +and determines the size of required working space.
> +The number of rounds of computation is controlled by the time parameter
> @var{t_cost}.
> +Use it to increase the cost of computation without raising the memory
> requirement.
> +Intermediate values of the algorithm are stored in the working buffer
> @var{scratch}
> +which must be allocated by the user.
> +To determine the minimum required size of the working buffer @var{scratch}
> use the utility function @code{balloon_itch}.
> +At last, the output will be written into the output buffer @var{dst} that
> has to be
> +at least @var{digest_size} bytes long.
> +Note that @var{dst} and @var{scratch} may point to the same buffer without
> causing any trouble.
> +@end deftypefun
I think it will make the docs more readable, and with less duplication,
if you add a paragraph to the introduction describing the inputs and
outputs of balloon. For a specific hash function, the inputs are the
password and salt, of arbitrary length, the t_const and s_cost
parameters, and the scratch buffer. The output is a digest of size
matching the digest size of the used hash function.
I think it would be good to explain that it's a common/reasonable use
case to use a large working storage, and that the purpose of large
working storage is to increase the cost of hardware accelerators built
by the adversary.
Then the reference for each function doesn't need to explain the purpose
t_cost and s_cost.
> +Next follows the utility function for computing the minimum required size of
> the working buffer
> +@var{scratch} for the @code{balloon} function.
I think it's better to explain the purpose of the scratch space and the
itch function in the section intro. Then you don't need to reintroduce
it here.
Regards,
/Niels
--
Niels Möller. PGP key CB4962D070D77D7FCB8BA36271D8F1FF368C6677.
Internet email is subject to wholesale government surveillance.
_______________________________________________
nettle-bugs mailing list -- nettle-bugs@lists.lysator.liu.se
To unsubscribe send an email to nettle-bugs-le...@lists.lysator.liu.se
