.TH LIBHASHSUM_INIT_HASHER 3 libhashsum .SH NAME libhashsum_init_hasher - initialise state for hashing .SH SYNOPSIS .nf #include \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; unsigned char \fIstandard_partial_byte_input_encoding\fP; unsigned char \fIstandard_partial_byte_output_encoding\fP; unsigned char \fIhash_excess_bits\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 (*\fIstretch\fP)(struct libhashsum_hasher *\fPthis\fP, int \fPskip\fP, void *\fPbuffer\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 and BLAKE2 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. .TP .B LIBHASHSUM_BLAKE2S Selects BLAKE2s (BLAKE2). See .BR libhashsum_init_blake2s_hasher (3) for more information. .TP .B LIBHASHSUM_BLAKE2B Selects BLAKE2b (BLAKE2). See .BR libhashsum_init_blake2b_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_excess_bits will be set to number of bits the last byte in the hash is padded with (it will be padded with cleared bits in its most significant part). .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. Its 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. However, if the user has already set .I hasher->hash_output to a .RI non- NULL pointer, the function will output the binary hash to that pointer instead without redirecting .I hasher->hash_output (the application must make sure this buffer is sufficiently large), provided that the library supports this behaviour for the selected hash function, otherwise it will behave as if .I hasher->hash_output was set to .IR NULL . 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->stretch will be set to .IR NULL , however upon successful completion of .I *hasher->finalise or .IR *hasher->finalise_const , .I hasher->stretch will be set to point to a function that can be used to extend the hash by .I hasher->hash_size bytes, and can be called repeated, provided that the hash function supports extending the hash. If the hash extention support is limited, .I *hasher->stretch will reset .I hasher->stretch to .I NULL once the limit has been reached. If the hash function supports generating hashes at any time, .I hasher->stretch will be set to point to a function at immediately. The hash extent will be written to a buffer in .I hasher->state (which .I *hasher->finalize and .I *hasher->finalize_const also write the hash to), and .I hasher->hash_output will be set to point to this buffer. .IR *hasher->stretch 's parameter .I this shall be .IR hasher . Its parameter .I skip can be set to non-zero if the hash extent should be discarded .RI ( hasher->hash_output will not be set in this case). Its parameter .I buffer shall be .I NULL for the above described behaviour, or an sufficiently large buffer the function shall output the hash extent to. If .I buffer is .RI non- NULL , .I hasher->hash_output will be set to .IR NULL ). .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 EXTENDED DESCRIPTION libhashsum has normalises the all implemented hash functions to always use the least significant bits in non-whole octets, however each hash function has its unstandarded. To make it easier to create an application the use the same encoding of partial octets as other application using any particular hash function, .B struct libhashsum_hasher contains two fields: .I standard_partial_byte_input_encoding and .IR standard_partial_byte_output_encoding ; which are merely informtional. They are not set to specify how libhashsum expects and encodes non-whole octets, but rather specify how partial bytes are encoded in the reference implementation or specification of a hash function. .PP If the hash function does not support non-whole input octets, .I this->standard_partial_byte_input_encoding will be set to .IR LIBHASHSUM_UNSUPPORTED . .PP If the hash function supports non-whole input octets, and uses the least significant bits in its standard, which is the same behaviour as implemented by libhashsum, .I this->standard_partial_byte_input_encoding will be set to .IR LIBHASHSUM_LEAST_SIGNIFICANT . .PP If the hash function supports non-whole input octets, and uses the most significant bits in its standard, which is the opposite behaviour of what is implemented by libhashsum, .I this->standard_partial_byte_input_encoding will be set to .IR LIBHASHSUM_MOST_SIGNIFICANT . This means that the partial octet must be reverted to convert between the libhashsum's encoding and the hash function's standard's encoding. .PP If the hash function does not support non-whole octet hashes, .I this->standard_partial_byte_output_encoding will be set to .IR LIBHASHSUM_UNSUPPORTED . .PP If the hash function supports non-whole octet hashes, and uses the least significant bits in its standard, which is the same behaviour as implemented by libhashsum, .I this->standard_partial_byte_output_encoding will be set to .IR LIBHASHSUM_LEAST_SIGNIFICANT . .PP If the hash function supports non-whole octet hashes, and uses the most significant bits in its standard, which is the opposite behaviour of what is implemented by libhashsum, .I this->standard_partial_byte_output_encoding will be set to .IR LIBHASHSUM_MOST_SIGNIFICANT . This means that the last octet, if partial, must be reverted to convert between the libhashsum's encoding and the hash function's standard's encoding. .SH HISTORY Introduced in libhashsum 1.0. .PP The .I hash_excess_bits field was added in libhashsum 1.1. .SH SEE ALSO .BR libhashsum (7), .BR libhashsum_init_hasher_from_string (3), .BR libhashsum_init_keccak_hasher (3)