diff options
author | Zoltan Fridrich <zfridric@redhat.com> | 2022-10-16 15:00:36 +0200 |
---|---|---|
committer | Niels Möller <nisse@lysator.liu.se> | 2022-10-16 15:00:36 +0200 |
commit | cf08f755ff812d7b281ad65148e723cf1aa65092 (patch) | |
tree | 63aded93b596bb7ca9f2bdedb286731e6cfbe42b | |
parent | 2c5fdb51309a70e6c21185d4980f005e525c8cf5 (diff) | |
download | nettle-cf08f755ff812d7b281ad65148e723cf1aa65092.tar.gz |
Documentation of Balloon hash.
-rw-r--r-- | nettle.texinfo | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/nettle.texinfo b/nettle.texinfo index 699ddb45..767ae718 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -4546,6 +4546,81 @@ salt @var{salt} of length @var{salt_length}, with iteration counter 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 @url{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. + +Each @acronym{BALLOON} function takes as an input a password and a salt of arbitrary +lengths, a time and a space parameters, and a scratch buffer. The space parameter +@var{s_cost} determines how many blocks of working space the algorithm will require +during its computation. It is common to set @var{s_cost} to a high value in order +to increase the cost of hardware accelerators built by the adversary. The time +parameter @var{t_cost} determines the number of rounds of computation that the algorithm +will perform. This can be used to further increase the cost of computation without raising +the memory requirement. Scratch buffer @var{scratch} is a user allocated working space +required by the algorithm. To determine the required size of the scratch buffer use the +utility function @code{balloon_itch}. Output of @acronym{BALLOON} algorithm will be +written into the output buffer @var{dst} that has to be at least @var{digest_size} bytes +long. Note that it is safe to use the same buffer for both @var{scratch} and @var{dst}. +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}, 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 a context for the +underlying hash function, which much 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. +@end deftypefun + +@deftypefun size_t balloon_itch (size_t @var{digest_size}, size_t @var{s_cost}) +Compute the size of the scratch 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}, uint8_t *@var{scratch}, uint8_t *@var{dst}) +@acronym{BALLOON} algorithm using SHA1 as the underlying hash function. +@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}, uint8_t *@var{scratch}, uint8_t *@var{dst}) +@acronym{BALLOON} algorithm using SHA256 as the underlying hash function. +@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}, uint8_t *@var{scratch}, uint8_t *@var{dst}) +@acronym{BALLOON} algorithm using SHA384 as the underlying hash function. +@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}, uint8_t *@var{scratch}, uint8_t *@var{dst}) +@acronym{BALLOON} algorithm using SHA512 as the underlying hash function. +@end deftypefun + + @node Public-key algorithms @section Public-key algorithms |