SipHash24 structv0.1.0
pub struct SipHash24 {
// private fields
}
Copy. Holds up to seven bytes of pending input alongside its state.
Associated functions
WithKey
pub func WithKey(low: uint64, high: uint64) -> SipHash24
A hasher keyed with low and high, with nothing written into it yet.
Both halves are read by value. The key must be unpredictable to whoever supplies the input — draw it from
Rux/Entropy at startup and keep it. A fixed key compiled into a program is a published key, and a published
key is no key at all.
Cannot fail. Runs in constant time and allocates nothing.
| Name | Type | Description |
|---|---|---|
low | uint64 | the key's first eight bytes as a word |
high | uint64 | the key's second eight bytes as a word |
Returns: a hasher keyed with those two words
WithKeyBytes
pub func WithKeyBytes(key: *byte) -> SipHash24
A hasher keyed with the sixteen bytes at key, least significant byte of each half first.
key is borrowed and read. This is the byte order the specification and every published test vector use, so
it is what to reach for when checking against one; WithKey is what to reach for when the key came from
Rux/Entropy as two words.
Cannot fail. Runs in constant time and allocates nothing.
key must be readable for sixteen bytes.
| Name | Type | Description |
|---|---|---|
key | *byte | sixteen key bytes, read as two little-endian words |
Returns: a hasher keyed with them
Methods
Reset
pub func Reset(self: &var SipHash24)
Puts the hasher back to where it started, keeping its key.
self is borrowed mutably. Everything written so far is forgotten; the key is not.
Cannot fail. Runs in constant time and allocates nothing.
Implements Hasher
SipHash24 conforms to Hasher.
Write
pub func Write(
self: &var SipHash24,
bytes: *byte,
length: uint
)
Adds length bytes at bytes to the hash.
bytes is borrowed and read; length is read by value. A zero length changes nothing and is the one case in
which bytes may be null. Input that does not fill an eight-byte word is held until the rest arrives, so any
division of the same byte stream into writes gives the same answer.
Runs in time proportional to length and allocates nothing.
bytes must be readable for length bytes.
| Name | Type | Description |
|---|---|---|
bytes | *byte | the bytes to absorb |
length | uint | how many bytes; zero absorbs nothing |
Finish
pub func Finish(self: &var SipHash24) -> uint64
The hash of everything written so far.
self is borrowed. Nothing is consumed: the finishing rounds run on a copy of the state, so asking twice
gives the same answer and writing more continues from where the writes left off.
Cannot fail. Runs in constant time and allocates nothing.
Returns: the hash of everything written since the last reset
Related
SipInit0
pub const SipInit0: uint64 = 0x736F6D6570736575;
The first initialization constant, mixed with the low half of the key. The four are the ASCII of "somepseudorandomlygeneratedbytes", split into eight-byte pieces — an arbitrary starting point chosen to be visibly arbitrary.
SipInit1
pub const SipInit1: uint64 = 0x646F72616E646F6D;
The second initialization constant, mixed with the high half of the key.
SipInit2
pub const SipInit2: uint64 = 0x6C7967656E657261;
The third initialization constant, mixed with the low half of the key.
SipInit3
pub const SipInit3: uint64 = 0x7465646279746573;
The fourth initialization constant, mixed with the high half of the key.
SipCompressionRounds
pub const SipCompressionRounds: uint = 2;
How many rounds each eight-byte word of input is mixed with: the 2 of SipHash-2-4.
SipFinalizationRounds
pub const SipFinalizationRounds: uint = 4;
How many rounds finish the hash after the last word: the 4 of SipHash-2-4.
SipState
pub struct SipState {
// private fields
}
The four words SipHash mixes, and the round that mixes them. Copy. Exposed because the round is the whole of the algorithm and worth being able to read, not because a caller has any reason to drive one directly.
Associated functions
FromKey
pub func FromKey(low: uint64, high: uint64) -> SipState
The state a key starts from.
low and high are the two halves of the 128-bit key, read by value.
Cannot fail. Runs in constant time and allocates nothing.
| Name | Type | Description |
|---|---|---|
low | uint64 | the key's first eight bytes as a word |
high | uint64 | the key's second eight bytes as a word |
Returns: the four-word state that key starts from
Methods
Round
pub func Round(self: &var SipState, count: uint)
Runs count SipHash rounds over the state.
self is borrowed mutably; count is read by value. Each round is four add-rotate-exclusive-or steps
arranged so that every word depends on every other after two of them.
Cannot fail. Runs in time proportional to count and allocates nothing.
| Name | Type | Description |
|---|---|---|
count | uint | how many rounds to run |
SipWord
pub func SipWord(bytes: *byte) -> uint64
The eight bytes at bytes as a 64-bit word, least significant byte first.
bytes is borrowed and read. Assembled a byte at a time, so the answer is the same at any address on any
machine: SipHash is defined on a little-endian byte stream rather than on the machine's own order.
Cannot fail. Runs in constant time and allocates nothing.
bytes must be readable for eight bytes.
Parameters
| Name | Type | Description |
|---|---|---|
bytes | *byte | eight bytes to read |
Returns: them as a little-endian word
SipHash24Of
pub func SipHash24Of(
bytes: *byte,
length: uint,
low: uint64,
high: uint64
) -> uint64
The SipHash-2-4 of length bytes at bytes, keyed with low and high.
bytes is borrowed and read; the rest are read by value. A zero length gives the hash of the empty input under
that key, and is the one case in which bytes may be null.
Cannot fail. Runs in time proportional to length and allocates nothing.
bytes must be readable for length bytes.
Parameters
| Name | Type | Description |
|---|---|---|
bytes | *byte | the bytes to hash |
length | uint | how many bytes |
low | uint64 | the key's first eight bytes as a word |
high | uint64 | the key's second eight bytes as a word |
Returns: their keyed hash