From bba0ac2dd39a9e2ddad6bb84beb9809b6df931b5 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 20 Sep 2015 13:27:15 +0200 Subject: info: representation conversion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- doc/info/libkeccak.texinfo | 46 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/info/libkeccak.texinfo b/doc/info/libkeccak.texinfo index 226a9d8..8c511ab 100644 --- a/doc/info/libkeccak.texinfo +++ b/doc/info/libkeccak.texinfo @@ -72,6 +72,7 @@ with support for bit-oriented data. * Selecting hash function:: Selecting and tuning the function. * State of the hashing:: The structure used to keep track of the hashing process. * Hashing messages:: Functions used to hash a message. +* Hexadecimal hashes:: Converting between binary and hexadecimal. * GNU Affero General Public License:: Copying and sharing libkeccak. * GNU Free Documentation License:: Copying and sharing this manual. @@ -481,7 +482,7 @@ The number of bits at the end of the message that are not covered by the third argument. This enables messages of non-whole byte length. @item -A @code{NUL}-terminated string of ASCII ones and zeroes, +A NUL-terminated string of ASCII ones and zeroes, describing the additional bits to suffix the message; or @code{NULL} if none. This is used to select between Keccak, SHA-3, RawSHAKE and SHAKE. Use one of the constants: @@ -497,7 +498,7 @@ For Keccak. @end table @item Output buffer for the hash, in binary. Should be -allocated to fit @code{(state.n + 7) / 8} @code{char}:s, +allocated to fit @code{(state.n + 7) / 8} @w{@code{char}:s}, where @code{state} is the state variable. Alternatively it may be @code{NULL}, in which case the hash is not retrieved. @@ -521,7 +522,46 @@ digests. The number of digests is specified in the second parameter. @item libkeccak_squeeze Squeeze out another digest. The hash will be stored in the second parameter, which should be allocated to fit -@code{(state.n + 7) / 8} @code{char}:s. +@code{(state.n + 7) / 8} @w{@code{char}:s}. +@end table + + + +@node Hexadecimal hashes +@chapter Hexadecimal hashes + +The functions that return hashes: @code{libkeccak_digest}, +@code{libkeccak_fast_digest} and @code{libkeccak_squeeze}, +store the hashes in binary format. However, it must often +preferred to have hashes in hexadecimal, so that they are +human-readable. This library hash two functions for +converting from binary to hexadecimal, and one function +for converting from hexadecimal to binary. Neither of +these functions have a return value. +@table @code +@item libkeccak_behex_lower +@itemx libkeccak_behex_upper +Convert from binary to hexadecimal. @code{libkeccak_behex_lower} +converts to lowercase hexadecimal, and @code{libkeccak_behex_upper} +converts to uppercase hexadecimal. Their first parameter +is the output buffer for the hexadecimal representation, +which will be NUL-terminated, it should be allocated to +fit @code{2 * n + 1} @w{@code{char}:s}, where @code{n} is +the length of the input hash. The second parameter is +the input hash, in binary. The third, and final, parameter +is the length of the input bash. + +@item libkeccak_unhex +Convert from hexadecimal to binary. Both uppercase and +lowercase, as well as mixed case, is supported as input. +The first parameter is the output buffer for the binary +representation, it should be allocated to fit +@code{strlen(hashsum) / 2} @w{@code{char}:s}, where +@code{hashsum} is the hash in hexadecimal, the input; +this is the number of bytes that will be stored in +the output. The second, and final, parameter is the +hash in hexadecimal, with must be NUL-terminated, +and have an even length. @end table -- cgit v1.2.3-70-g09d2