Hello Niels,
Here is the documentation patch for the balloon algorithm.
Could you please review the text?
Kind regards
Zoltan
On Mon, Sep 19, 2022 at 12:54 PM Zoltan Fridrich <zfrid...@redhat.com>
wrote:
> Hello,
>
> I made some small changes.
>
> - removed fail variable in tests
> - added Red Hat copyright
> - added condition before calling hash update() function where the
> input can be NULL or length can be 0
>
> I will be working on the documentation for the balloon function now.
>
> Kind regards,
> Zoltan
>
> On Mon, Sep 19, 2022 at 10:21 AM Zoltan Fridrich <zfrid...@redhat.com>
> wrote:
>
>> Hi Niels,
>>
>> I wasn't responding because I was on a vacation. I will take a look at it
>> now.
>>
>> On Thu, Sep 15, 2022 at 8:02 PM Niels Möller <ni...@lysator.liu.se>
>> wrote:
>>
>>> ni...@lysator.liu.se (Niels Möller) writes:
>>>
>>> > Thanks, merged to a new branch, "balloon", for testing.
>>>
>>> The ubsan test failed (built with CFLAGS="-fsanitize=undefined
>>> -fno-sanitize-recover -g -O2"). See
>>> https://gitlab.com/gnutls/nettle/-/jobs/3029478202, could e.g, be a call
>>>
>>> sha256_update(ctx, 0, NULL)
>>>
>>> which results in a call to memcpy(..., NULL, 0). Mostly harmless in
>>> itself, but violates the non-null annotation on glibc memcpy, shouldn't
>>> happen, and might be a sign of additional problems.
>>>
>>> Can you investigate, and post a patch relative to the balloon branch? If
>>> you do another patch, please also consider simplifying the tests by
>>> eliminating the "fail" variable.
>>>
>>> Regards,
>>> /Niels
>>>
>>> --
>>> Niels Möller. PGP key CB4962D070D77D7FCB8BA36271D8F1FF368C6677.
>>> Internet email is subject to wholesale government surveillance.
>>>
>>>
diff --color -ruNp b/nettle.texinfo c/nettle.texinfo
--- b/nettle.texinfo 2022-09-19 10:51:07.260226612 +0200
+++ c/nettle.texinfo 2022-09-22 11:01:58.690956597 +0200
@@ -4455,6 +4455,136 @@ salt @var{salt} of length @var{salt_leng
room for at least @var{length} octets.
@end deftypefun
+
+@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
+
+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})
+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.
+@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
+
+Next follows the utility function for computing the minimum required size of the working buffer
+@var{scratch} for the @code{balloon} function.
+
+@deftypefun size_t balloon_itch (size_t @var{digest_size}, size_t @var{s_cost})
+Compute the size of the working buffer @var{scratch}. @var{digest_size} is the
+digest size of the chosen hash algorithm. @var{s_cost}
+is the space parameter used by the @code{balloon} function.
+@end deftypefun
+
+@subsection Concrete @acronym{BALLOON} functions
+Here follows a list of the specialized @acronym{BALLOON} functions, which are
+more user-friendly variants of the general function.
+
+@subsubsection @acronym{BALLOON-SHA1}
+
+@deftypefun void balloon_sha1 (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})
+@acronym{BALLOON} algorithm using SHA1 as the underlying hash function.
+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}.
+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
+
+@subsubsection @acronym{BALLOON-SHA256}
+
+@deftypefun void balloon_sha256 (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})
+@acronym{BALLOON} algorithm using SHA256 as the underlying hash function.
+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}.
+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
+
+@subsubsection @acronym{BALLOON-SHA384}
+
+@deftypefun void balloon_sha384 (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})
+@acronym{BALLOON} algorithm using SHA384 as the underlying hash function.
+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}.
+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
+
+@subsubsection @acronym{BALLOON-SHA512}
+
+@deftypefun void balloon_sha512 (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})
+@acronym{BALLOON} algorithm using SHA512 as the underlying hash function.
+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}.
+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
+
+
@node Public-key algorithms
@section Public-key algorithms
_______________________________________________
nettle-bugs mailing list -- nettle-bugs@lists.lysator.liu.se
To unsubscribe send an email to nettle-bugs-le...@lists.lysator.liu.se
