hash.h
SHA-256, MD5 and Whirlpool.
#include <sonore/hash.h>- 3types
- 6other declarations
On this page
Design notes
Why a hash is in an audio SDK at all
Two jobs, both about NAMING things by their content rather than by where they came from:
- A sample a plugin loaded. Two projects referencing the same kick drum should agree that it is the same kick drum, and a path does not tell you that -- the same file lives at a different path on every machine.
- A state blob. "Has this preset changed since it was saved" is a question about bytes, and comparing bytes to bytes gets slower as the state gets bigger while comparing 32 of them does not.
Which one
SHA-256, unless something outside this SDK names another. It is the one every other system in this project speaks, and the only one of the three whose collision resistance anybody still relies on.
MD5 is here for the files and tools that name it: a sample pack's manifest of MD5 sums, a catalogue keyed on one, a digest the reference computed. It is BROKEN as a security hash -- two different files with the same MD5 are an afternoon's work on a laptop -- so it identifies data nobody is attacking and never vouches for data somebody might be.
Whirlpool is the reference's 512-bit hash, here so a digest made there can be checked here. Nothing in this SDK picks it on its own merits.
Every one is tested against its published vectors (RFC 1321's suite, the FIPS examples, the ISO/NESSIE set), because a hash nobody checks against somebody else's answers is a hash that agrees only with itself.
NOT for passwords. A bare hash is the wrong tool for those and none of these has a salt or a work factor -- if that job ever appears here it wants a purpose-built KDF, not this file with a loop around it.
Written from FIPS 180-4, RFC 1321 and the Whirlpool specification, which are descriptions of arithmetic. SHA-256's constants are the first thirty-two bits of the fractional parts of cube roots of primes; Whirlpool's S-box and its round tables are BUILT at first use from the specification's three 4-bit mini-boxes and its circulant matrix, rather than pasted in as 2,048 opaque words. Derived, not copied: a typo in a derivation breaks every vector, where a typo in a pasted table can break only the inputs that reach that entry.
Types 3
A SHA-256 in progress.
Streaming, because the thing most worth hashing here is a file too big to want a second copy of in memory.
An MD5 in progress (RFC 1321), streaming like Sha256 and with the same shape: update, then finish or hex, and finishing leaves the state alone.
For interoperating with something that already names MD5 -- read the header before reaching for it for anything else.
A Whirlpool in progress: the final (2003) version of the algorithm, as ISO/IEC 10118-3 standardises it and the NESSIE vectors pin down -- not Whirlpool-0 or Whirlpool-T, which share the name and not the output.
512-bit digest, 512-bit blocks, a 256-bit length counter. Same shape as the others: update, then finish or hex.
Functions 6
- fn
inline std::string sha256Hex(const void* data, size_t bytes)The whole of a buffer, in one call.hash::sha256Hex · hash.h:240 - fn
inline std::string sha256File(const char* path)A file, streamed. Empty when it cannot be read -- see streamFile.hash::sha256File · hash.h:252 - fn
inline std::string md5Hex(const void* data, size_t bytes)The MD5 of a whole buffer, as 32 lowercase hex characters.hash::md5Hex · hash.h:389 - fn
inline std::string md5File(const char* path)A file, streamed. Empty when it cannot be read -- see streamFile.hash::md5File · hash.h:399 - fn
inline std::string whirlpoolHex(const void* data, size_t bytes)The Whirlpool of a whole buffer, as 128 lowercase hex characters.hash::whirlpoolHex · hash.h:582 - fn
inline std::string whirlpoolFile(const char* path)A file, streamed. Empty when it cannot be read -- see streamFile.hash::whirlpoolFile · hash.h:594