STOEPLITZ_TO_KEY(9) | Kernel Developer's Manual | STOEPLITZ_TO_KEY(9)

# NAME

`stoeplitz_to_key`, `stoeplitz_eaddr`, `stoeplitz_ip4`, `stoeplitz_ip4port`, `stoeplitz_ip6`, `stoeplitz_ip6port` — symmetric Toeplitz hash API

# SYNOPSIS

`#include <net/toeplitz.h>`

void
`stoeplitz_to_key`(void *key, size_t keylen);

uint16_t
`stoeplitz_eaddr`(const uint8_t *eaddr);

uint16_t
`stoeplitz_ip4`(uint32_t srcaddr, uint32_t dstaddr);

uint16_t
`stoeplitz_ip4port`(uint32_t srcaddr, uint32_t dstaddr, uint16_t srcport, uint16_t dstport);

uint16_t
`stoeplitz_ip6`(const struct in6_addr *srcaddr, const struct in6_addr *dstaddr);

uint16_t
`stoeplitz_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_eaddr`() calculates a hash value for a single Ethernet address.

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

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

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

`stoeplitz_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_eaddr`(), `stoeplitz_ip4`(), `stoeplitz_ip4port`(), `stoeplitz_ip6`(), and `stoeplitz_ip6port`() can be called during autoconf, from process context, or from an interrupt context.

# RETURN VALUES

`stoeplitz_eaddr`(), `stoeplitz_ip4`(), `stoeplitz_ip4port`(), `stoeplitz_ip6`(), and `stoeplitz_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.

January 16, 2022 | Debian