linux-imx

===========================

SipHash - a short input PRF

===========================

​

:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>

​

SipHash is a cryptographically secure PRF -- a keyed hash function -- that

performs very well for short inputs, hence the name. It was designed by

cryptographers Daniel J. Bernstein and Jean-Philippe Aumasson. It is intended

as a replacement for some uses of: `jhash`, `md5_transform`, `sha_transform`,

and so forth.

​

SipHash takes a secret key filled with randomly generated numbers and either

an input buffer or several input integers. It spits out an integer that is

indistinguishable from random. You may then use that integer as part of secure

sequence numbers, secure cookies, or mask it off for use in a hash table.

​

Generating a key

================

​

Keys should always be generated from a cryptographically secure source of

random numbers, either using get_random_bytes or get_random_once::

​

    siphash_key_t key;

    get_random_bytes(&key, sizeof(key));

​

If you're not deriving your key from here, you're doing it wrong.

​

Using the functions

===================

​

There are two variants of the function, one that takes a list of integers, and

one that takes a buffer::

​

    u64 siphash(const void *data, size_t len, const siphash_key_t *key);

​

And::

​

    u64 siphash_1u64(u64, const siphash_key_t *key);

    u64 siphash_2u64(u64, u64, const siphash_key_t *key);

    u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);

    u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);

    u64 siphash_1u32(u32, const siphash_key_t *key);

    u64 siphash_2u32(u32, u32, const siphash_key_t *key);

    u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);

    u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);

​

If you pass the generic siphash function something of a constant length, it

will constant fold at compile-time and automatically choose one of the

optimized functions.

​

Hashtable key function usage::

​

    struct some_hashtable {

        DECLARE_HASHTABLE(hashtable, 8);

        siphash_key_t key;

    };

​

    void init_hashtable(struct some_hashtable *table)

    {

        get_random_bytes(&table->key, sizeof(table->key));

    }

​