Repository navigation
CSipHash
#include <certpp/crypto/siphash.hpp> --- certpp::crypto
SipHash-2-4 (Aumasson and Bernstein, "SipHash: a fast short-input PRF"), a keyed PRF taking a 128-bit key and producing a 64-bit output. RFC 9018 2.2 specifies it as the algorithm for DNS server cookies, which is what it is here for.
Unlike CPoly1305 this is a long-lived keyed primitive, not a one-time authenticator: the
key may authenticate any number of messages, reset() may be called repeatedly to start a
new message under the same or a different key, and finish() leaves the key in place so the
instance stays usable. That is SipHash's own security model, and the difference from
Poly1305 is not a convenience -- reusing a Poly1305 key hands an attacker forgeries, while
reusing a SipHash key is the intended mode of operation.
It is also not an IHasher, and deliberately so: IHasher is unkeyed and its
implementations have digests of 16 bytes and up, while this is keyed and emits 8 bytes. A
64-bit output is far too short to resist a collision search, so SipHash is a message
authenticator and a hash-table defence, never a digest to identify or sign data with --
letting it sit behind IHasher would invite exactly that mistake.
The construction is an ARX sponge over four 64-bit words: each 8-byte message block is XORed into v3, run through 2 SipRounds, then XORed into v0; after the final block (which always carries the message length mod 256 in its top byte) v2 is XORed with 0xFF and 4 more SipRounds finalize, the output being v0 ^ v1 ^ v2 ^ v3. The "2-4" in the name is those two round counts.
-
static constexpr size_t KEY_BYTES = 16--- Key length in bytes. -
static constexpr size_t TAG_BYTES = 8--- Output length in bytes. -
static constexpr size_t BLOCK_BYTES = 8--- Message block length in bytes.
Constructs an unkeyed instance; call reset() before pushing anything.
Destructor; clears the key and state.
Keys this instance and starts a fresh message. May be called as often as wanted, with a key that has already been used -- SipHash is a reusable PRF, not a one-time MAC.
-
key--- Exactly KEY_BYTES.
Returns: true on success; false if the key is the wrong size.
Starts a fresh message under the key already in place, which finish() leaves intact.
Returns: true on success; false if this instance has never been keyed.
Absorbs message bytes. May be called with any lengths; blocks are buffered internally.
-
buf--- The data to authenticate.
Returns: The number of bytes absorbed; 0 if this instance is not keyed.
Finalizes the current message and writes the 64-bit output little-endian, as the reference implementation and RFC 9018 do.
Unlike CPoly1305::finish() this does not consume the key: the state is left ready for
reset() to begin another message under the same key.
-
out--- Exactly TAG_BYTES.
Returns: true on success.
static bool compute( const SReadOnlyByteSpan& key, const SReadOnlyByteSpan& message, const SByteSpan& out )
One-shot SipHash-2-4.
-
key--- Exactly KEY_BYTES; may be reused across calls. -
message--- The message. -
out--- Exactly TAG_BYTES.
Returns: true on success.
Computes a DNS server cookie (RFC 9018 2.2). Unlike CPoly1305 the key is long-lived: finish() leaves it in place, and the no-argument reset() starts the next message under the same key.
// given: const SReadOnlyByteSpan& serverSecret, const SReadOnlyByteSpan& clientCookie, const SReadOnlyByteSpan& clientIp
crypto::CSipHash prf;
if (!prf.reset(serverSecret)) {
return; // the key is exactly KEY_BYTES, which is 16
}
prf.push(clientCookie);
prf.push(clientIp);
uint8_t cookieHash[crypto::CSipHash::TAG_BYTES];
SByteSpan out(cookieHash, sizeof(cookieHash));
if (!prf.finish(out)) {
return;
}
// The same instance serves the next query without re-supplying the key.
if (!prf.reset()) {
return;
}Reference generated from certpp/crypto/siphash.hpp at commit 0834b29 (v1.0.1). The header is authoritative --- if this page disagrees with it, the header is right and this page needs regenerating.