diff options
Diffstat (limited to 'libhashsum_init_hasher.3')
| -rw-r--r-- | libhashsum_init_hasher.3 | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/libhashsum_init_hasher.3 b/libhashsum_init_hasher.3 new file mode 100644 index 0000000..df8c382 --- /dev/null +++ b/libhashsum_init_hasher.3 @@ -0,0 +1,414 @@ +.TH LIBHASHSUM_INIT_HASHER 3 libhashsum +.SH NAME +libhashsum_init_hasher - initialise state for hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBenum libhashsum_algorithm\fP { /* see the section DESCRIPTION for a listing of values */ }; + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, enum libhashsum_algorithm \fIalgorithm\fP); +.fi +.PP +Link with +.I -lhashsum +.br +.I -lsha1 +(unless support for SHA-0 and SHA-1 was excluded) +.br +.I -lsha2 +(unless support for SHA-2 was excluded) +.br +.I -lkeccak +(unless support for Keccak, SHA-3, SHAKE, and RawSHAKE was excluded) +.br +.I -lblake +(unless support for BLAKE was excluded). + +.SH DESCRIPTION +The +.B libhashsum_init_hasher +function initialises +.I *hasher +for hashing using a cryptographic hash function selected +using the parameter +.IR algorithm , +and stores hash function information and +hashing functions in +.IR *hasher . +.PP +.I algorithm +shall be one of the following values to select hash function: +.TP +.B LIBHASHSUM_MD2 +Selects MD2. See +.BR libhashsum_init_md2_hasher (3) +for more information. +.TP +.B LIBHASHSUM_MD4 +Selects MD4. See +.BR libhashsum_init_md4_hasher (3) +for more information. +.TP +.B LIBHASHSUM_MD5 +Selects MD5. See +.BR libhashsum_init_md5_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_128 +Selects RIPEMD-128. See +.BR libhashsum_init_ripemd_128_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_160 +Selects RIPEMD-160. See +.BR libhashsum_init_ripemd_160_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_256 +Selects RIPEMD-256. See +.BR libhashsum_init_ripemd_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_512 +Selects RIPEMD-512. See +.BR libhashsum_init_ripemd_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA0 +Selects SHA-0. See +.BR libhashsum_init_sha0_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA1 +Selects SHA-1. See +.BR libhashsum_init_sha0_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_224 +Selects SHA-224 (SHA-2). See +.BR libhashsum_init_sha_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_256 +Selects SHA-256 (SHA-2). See +.BR libhashsum_init_sha_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_384 +Selects SHA-384 (SHA-2). See +.BR libhashsum_init_sha_384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_512 +Selects SHA-512 (SHA-2). See +.BR libhashsum_init_sha_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_512_224 +Selects SHA-512/224 (SHA-2). See +.BR libhashsum_init_sha_512_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_512_256 +Selects SHA-512/256 (SHA-2). See +.BR libhashsum_init_sha_512_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK +Selects Keccak. However, this value is +unsupported, as parameters are expected +(even though they are technically optional), +so the function will return -1 and set +.I errno +to +.IR EINVAL . +See +.BR libhashsum_init_keccak_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_224 +Selects Keccak-224 (Keccak[n=224]). See +.BR libhashsum_init_keccak_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_256 +Selects Keccak-256 (Keccak[n=256]). See +.BR libhashsum_init_keccak_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_384 +Selects Keccak-384 (Keccak[n=384]). See +.BR libhashsum_init_keccak_384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_512 +Selects Keccak-512 (Keccak[n=512]). See +.BR libhashsum_init_keccak_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_224 +Selects SHA-3-224. See +.BR libhashsum_init_sha3_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_256 +Selects SHA-3-256. See +.BR libhashsum_init_sha3_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_384 +Selects SHA-3-384. See +.BR libhashsum_init_sha3_384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_512 +Selects SHA-3-512. See +.BR libhashsum_init_sha3_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHAKE128 +Selects SHAKE128 (SHAKE). See +.BR libhashsum_init_shake128_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHAKE256 +Selects SHAKE256 (SHAKE). See +.BR libhashsum_init_shake256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHAKE512 +Selects SHAKE512 (SHAKE). See +.BR libhashsum_init_shake512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RAWSHAKE128 +Selects RawSHAKE128 (RawSHAKE). See +.BR libhashsum_init_rawshake128_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RAWSHAKE256 +Selects RawSHAKE256 (RawSHAKE). See +.BR libhashsum_init_rawshake256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RAWSHAKE512 +Selects RawSHAKE512 (RawSHAKE). See +.BR libhashsum_init_rawshake512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE224 +Selects BLAKE224 (BLAKE, BLAKEs). See +.BR libhashsum_init_blake224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE256 +Selects BLAKE256 (BLAKE, BLAKEs). See +.BR libhashsum_init_blake256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE384 +Selects BLAKE384 (BLAKE, BLAKEb). See +.BR libhashsum_init_blake384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE512 +Selects BLAKE512 (BLAKE, BLAKEb). See +.BR libhashsum_init_blake512_hasher (3) +for more information. +.PP +.I hasher->algorithm +will be set to +.IR algorithm . +.PP +.I hasher->algorithm_string +will be set to a string representing the hash +function selected using the parameter +.IR algorithm . +.PP +.I hasher->input_block_size +will be set to the block size, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes. +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 if +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter, or to 0 otherwise. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.TP +.B EINVAL +.I extra_bits +is not 0 but +.I hasher->supports_non_whole_bytes +was set to 0 by +.BR libhashsum_init_hasher . +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will either be set to +.I NULL +or to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOSYS +The selected algorithm requires a larger +(newer) version +.B union libhashsum_state +(and thus a larger version of +.BR "struct libhashsum_hasher" ) +than the application is compiled with. +.TP +.B EINVAL +The value of +.I algorithm +is unrecognised or unsupported. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_hasher_from_string (3), +.BR libhashsum_init_keccak_hasher (3) |