diff options
Diffstat (limited to '')
-rw-r--r-- | doc/man/libkeccak_hmac_digest.3 | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/doc/man/libkeccak_hmac_digest.3 b/doc/man/libkeccak_hmac_digest.3 new file mode 100644 index 0000000..bd50b2c --- /dev/null +++ b/doc/man/libkeccak_hmac_digest.3 @@ -0,0 +1,103 @@ +.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_digest(libkeccak_hmac_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_digest () +function absorbes the last part of (or all of) a message, +and returns the HMAC hash of the entire message. The last +part of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_hmac_update (3) +function or the +.BR libkeccak_hmac_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s +and '0':s, representing the bits that should be appended +to the message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_hmac_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_hmac_digest () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_digest () +function may fail for any reason specified by the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_update (3), +.BR libkeccak_hmac_fast_digest (3), +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se |