DOCSEARCHbyAlgolia
Submit Docs

minio/highwayhash

repository·master·Indexed 21 days ago

https://github.com/minio/highwayhash

A high-performance pseudo-random-function (PRF) implementation in Go with optimized assembly for Intel, ARM, and ppc64le architectures. It supports 64, 128, and 256-bit hash values and is designed for fingerprinting and preventing hash-flooding attacks. It is not a replacement for strong cryptographic hash functions. Requires Go 1.11 or higher for optimized assembly.

Tokens
992
Snippets
3
Records
6
Agent score
26%

What's inside highwayhash

  1. What is HighwayHash and when to use it

    master

    HighwayHash is a high-performance pseudo-random-function (PRF) that takes a 256-bit key and computes 64, 128, or 256-bit hash values.

    Use cases:

    • Preventing hash-flooding attacks.
    • Authenticating short-lived messages.
    • Fingerprinting functions.

    Important Limitations:

    • HighwayHash is not a general-purpose cryptographic hash function (like Blake2b, SHA-3, or SHA-2).
    • Do not use it if strong collision resistance is required.

    Stability: All three output sizes (64, 128, and 256 bits) are declared stable, meaning hash results for a given input are guaranteed not to change.

  4. Use Digest for streaming hash computation

    master

    If you need to hash data incrementally (e.g., reading from a stream), use the Digest types which implement the standard hash.Hash interface. These constructors return an error if the key is not 32 bytes long, rather than panicking.

    • NewDigest(key []byte) (*Digest, error): Returns a *Digest for 256-bit hashing.
    • NewDigest128(key []byte) (*Digest, error): Returns a *Digest for 128-bit hashing.
    • NewDigest64(key []byte) (*Digest64, error): Returns a *Digest64 for 64-bit hashing.

    Methods available on Digest and Digest64:

    • Write(p []byte) (n int, err error): Adds data to the hash.
    • Sum(b []byte) []byte: Appends the current hash to the provided slice.
    • Reset(): Resets the hash to its initial state using the original key.
    • Sum64() uint64: (Only on Digest64) Returns the 64-bit hash value.
    package main

import (
	"fmt"
	"github.com/minio/highwayhash"
)

func main() {
	key := make([]byte, 32)
	h, err := highwayhash.NewDigest(key)
	if err != nil {
		panic(err)
	}

	h.Write([]byte("part 1 "))
	h.Write([]byte("part 2"))

	// Get 256-bit result
	sum := h.Sum(nil)
	fmt.Printf("Hash: %x\n", sum)
}

  5. Compute HighwayHash checksums using Sum functions

    master

    For a quick, one-shot computation of a hash without managing state, use the Sum family of functions. These functions take the data and a 32-byte key and return the result immediately. Note that these functions will panic if the provided key is not exactly 32 bytes long.

    • Sum(data, key []byte) [32]byte: Returns a 256-bit hash.
    • Sum128(data, key []byte) [16]byte: Returns a 128-bit hash.
    • Sum64(data, key []byte) uint64: Returns a 64-bit hash.
    package main

import "github.com/minio/highwayhash"

func main() {
	key := make([]byte, 32) // Must be 32 bytes
	data := []byte("hello world")

	// 256-bit
	h256 := highwayhash.Sum(data, key)

	// 128-bit
	h128 := highwayhash.Sum128(data, key)

	// 64-bit
	h64 := highwayhash.Sum64(data, key)
    _ = h256
    _ = h128
    _ = h64
}

  6. Reference HighwayHash constants and error conditions

    master

    The following constants define the output sizes for the different HighwayHash variants:

    • Size: 32 bytes (256-bit)
    • Size128: 16 bytes (128-bit)
    • Size64: 8 bytes (64-bit)

    Error Behavior:

    • When using New, New128, or New64 (which return hash.Hash interfaces), an error is returned if the key length is not Size (32 bytes).
    • When using Sum, Sum128, or Sum64, the code will panic if the key length is not 32 bytes.