4.1 KiB
Executable file
Note the Generic Hashing section of the libsodium documentation, on which this document heavily depends.
Implemented using BLAKE2b. This function set should not be used to hash passwords. Use crypto_pwhash instead.
crypto_generichash(out_size, in, key)
Compute a fixed length fingerprint for a message of arbitrary length. Use cases include file integrity checks (fulfilling a similar role to MD5 and SHA-1, but with better security) and creating unique identifiers to index data of arbitrary length.
Parameters
out_size: Number, Output length in bytes. Should be between crypto_generichash_BYTES_MIN and crypto_generichash_BYTES_MAX (inclusive). The minimum recommended size is crypto_generichash_BYTES.
in: Buffer, Message to hash.
key: Buffer, Should be between crypto_generichash_KEYBYTES_MIN and crypto_generichash_KEYBYTES_MAX (inclusive). Note the recommended size: crypto_generichash_KEYBYTES. Key can also be null, in which case the output will always have the same fingerprint. If a key is specified, different keys hashing the same message should produce different fingerprints.
Returns
Buffer, Containing the resulting hash.
crypto_generichash_init(key, out_size)
Initialize a state in order to eventually produce an output of length out_size.
Together with crypto_generichash_update and crypto_generichash_final, forms the generichash streaming API. Useful for very large files or data streams.
Parameters
key: Buffer, See restrictions for generichash keys, above. Can be null.
out_size: Number, Eventual output length, in bytes.
Returns
Buffer, Containing state. Passed as initial parameter to crypto_generichash_update and crypto_generichash_final.
crypto_generichash_update(state, message)
Process a chunk of the eventual completed message.
Parameters
state: Buffer, The result of a call to crypto_generichash_init or a previous call to crypto_generichash_update.
message: Buffer, Chunk of message to add.
Returns
Buffer, Containing state.
crypto_generichash_final(state, out_size)
Obtain the output hash as a result of the streaming API state.
Parameters
state: Buffer, The result of a call to crypto_generichash_update.
out_size: Number, Output length, in bytes.
Returns
Buffer, Containing the resulting hash.
crypto_generichash_BYTES_MIN
Minimum permitted length of output hash, in bytes. Algorithm-specific variant: crypto_generichash_blake2b_BYTES_MIN.
crypto_generichash_BYTES_MAX
Maximum permitted length of output hash, in bytes. Algorithm-specific variant: crypto_generichash_blake2b_BYTES_MAX.
crypto_generichash_BYTES
Recommended length of output hash to effectively ensure that two messages will not share the same fingerprint. Algorithm-specific variant: crypto_generichash_blake2b_BYTES.
crypto_generichash_KEYBYTES_MIN
Minimum permitted length of key, in bytes. Algorithm-speficic variant: crypto_generichash_blake2b_KEYBYTES_MIN.
crypto_generichash_KEYBYTES_MAX
Maximum permitted length of key, in bytes. Algorithm-specific variant: crypto_generichash_blake2b_KEYBYTES_MAX.
crypto_generichash_KEYBYTES
Recommended length of key, in bytes. Note that key can also be null, which leads to the message always having the same fingerprint. Algorithm-specific variant: crypto_generichash_blake2b_KEYBYTES.
Note
Node Sodium also exposes crypto_generichash_blake2b, crypto_generichash_blake2b_init, crypto_generichash_blake2b_update, and crypto_generichash_blake2b_final. In the interests of brevity these are not separately documented, but their usage and parameters are identical (with the exception of constant naming: see above list).