STOEPLITZ_TO_KEY(9)

NAME
stoeplitz_to_key, stoeplitz_hash_ip4, stoeplitz_hash_ip4port, stoeplitz_hash_ip6, stoeplitz_hash_ip6port - symmetric Toeplitz hash API

SYNOPSIS
#include <net/toeplitz.h>
void
stoeplitz_to_key(void *key, size_t keylen);
uint16_t
stoeplitz_hash_ip4(uint32_t srcaddr, uint32_t dstaddr);
uint16_t
stoeplitz_hash_ip4port(uint32_t srcaddr, uint32_t dstaddr, uint16_t srcport, uint16_t dstport);
uint16_t
stoeplitz_hash_ip6(const struct in6_addr *srcaddr, const struct in6_addr *dstaddr);
uint16_t
stoeplitz_hash_ip6port(const struct in6_addr *srcaddr, const struct in6_addr *dstaddr, uint16_t srcport, uint16_t dstport);

DESCRIPTION
The Toeplitz hash algorithm is commonly used by network interface controllers to generate a short hash based on the value of fields in network packet headers. The resulting hash value can be used as a flow identifier, which in turn can be used to consistently select a context for processing packets using those fields. Traditionally, the Toeplitz hash produces different results depending on the order of inputs, i.e. adding port 80 then 1234 as inputs would produce a different result to hashing port 1234 then 80.

The symmetric Toeplitz API uses a key selected to generate the same hash result regardless of the order the inputs were added. The API also supports producing Toeplitz hash keys for use by network interface controllers that provide the same symmetric property.

The stoeplitz_to_key() function generates a Toeplitz key for use by a network interface controller based on the system's symmetric Toeplitz key. A Toeplitz key of keylen bytes will be written to the buffer referenced by the key argument. keylen must be a multiple of 2 bytes.

stoeplitz_hash_ip4() calculates a hash value for a pair of IPv4 addresses.

stoeplitz_hash_ip4port() calculates a hash value for a pair of IPv4 addresses and ports as used by protocols like TCP or UDP.

stoeplitz_hash_ip6() calculates a hash value for a pair of IPv6 addresses.

stoeplitz_hash_ip6port() calculates a hash value for a pair of IPv6 addresses and ports as used by protocols like TCP or UDP.

CONTEXT
stoeplitz_to_key(), stoeplitz_hash_ip4(), stoeplitz_hash_ip4port(), stoeplitz_hash_ip6(), and stoeplitz_hash_ip6port() can be called during autoconf, from process context, or from an interrupt context.

RETURN VALUES
stoeplitz_hash_ip4(), stoeplitz_hash_ip4port(), stoeplitz_hash_ip6(), and stoeplitz_hash_ip6port() return a 16-bit hash value in host byte order.

HISTORY
The symmetric Toeplitz API is based on the ideas and implementation in DragonFly by Yanmin Qiao <sephe@dragonflybsd.org> and Simon Schubert <corecode@fs.ei.tum.de>.

The API appeared in OpenBSD 6.8.