The crypto_generichash() function puts a fingerprint of the message in whose length is inlen bytes into out. The output size can be chosen by the application.
The minimum recommended output size is crypto_generichash_BYTES. This size makes it practically impossible for two messages to produce the same fingerprint.
But for specific use cases, the size can be any value between crypto_generichash_BYTES_MIN (included) and crypto_generichash_BYTES_MAX (included).
key can be NULL and keylen can be 0. In this case, a message will always have the same fingerprint, similar to the MD5 or SHA-1 functions for which crypto_generichash() is a faster and more secure alternative.
But a key can also be specified. A message will always have the same fingerprint for a given key, but different keys used to hash the same message are very likely to produce distinct fingerprints.
In particular, the key can be used to make sure that different applications generate different fingerprints even if they process the same data.
The recommended key size is crypto_generichash_KEYBYTES bytes.
However, the key size can by any value between crypto_generichash_KEYBYTES_MIN (included) and crypto_generichash_KEYBYTES_MAX (included).
The message doesn't have to be provided as a single chunk. The generichash operation also supports a streaming API.
The crypto_generichash_init() function initializes a state state with a key key (that can be NULL) of length keylen bytes, in order to eventually produce outlen bytes of output.
Each chunk of the complete message can then be sequentially processed by calling crypto_generichash_update(), providing the previously initialized state state, a pointer to the chunk in and the length of the chunk in bytes, inlen.
The crypto_generichash_final() function completes the operation and puts the final fingerprint into out as outlen bytes.
After crypto_generichash_final() returns, the state should not be used any more, unless it is reinitialized using crypto_generichash_init().
This alternative API is especially useful to process very large files and data streams.
The crypto_generichash_keygen() function creates a key k of the recommended length crypto_generichash_KEYBYTES.
State structure size
The crypto_generichash_state structure length is either 357 or 361 bytes. 64-bytes alignment is required. For dynamically allocated states, crypto_generichash_statebytes() returns the rounded up structure size, and should be prefered to sizeof().
The crypto_generichash_* function set is implemented using BLAKE2b, a simple, standardized (RFC 7693) secure hash function that is as strong as SHA-3 but faster than SHA-1 and MD5.
Unlike MD5, SHA-1 and SHA-256, this function is safe against hash length extension attacks.
BLAKE2b's salt and personalisation parameters are accessible through the lower-level functions whose prototypes are defined in crypto_generichash_blake2b.h.
BLAKE2b is not suitable for hashing passwords. For this purpose, use the crypto_pwhash API documented in the Password Hashing section.