hash

Documentation

Overview

Package hash holds the hashing primitives ported from cpython/Python/pyhash.c and cpython/Python/bootstrap_hash.c.

In v0.1 only the secret-bootstrap half is implemented. The full SipHash-1-3, FNV, and x86_aes hashers land with pyhash.c in v0.4.

Index

• Constants
• Variables
• func Reset()
• type Config
• type SecretMode
  • func Init(cfg *Config) (SecretMode, error)

Constants

const SecretSize = 24

SecretSize is the size of the hash secret. Matches sizeof(_Py_HashSecret_t) in CPython 3.14: 16 bytes of SipHash key followed by 8 bytes of FNV salt.

CPython: Include/internal/pycore_pyhash.h:L42 _Py_HashSecret_t

Variables

var ErrInvalidSeed = errors.New("hash: PYTHONHASHSEED must be \"random\", \"0\", or a non-negative integer in [1, 4294967295]")

ErrInvalidSeed is returned by Init when PYTHONHASHSEED is set to a value that is neither "random", "0", nor a non-negative 32-bit integer.

var Secret [SecretSize]byte

Secret is the per-process hash secret. v0.4 will read it from the hashers; until then, callers only seed it.

CPython: Include/internal/pycore_pyhash.h:L67 _Py_HashSecret

Functions

func Reset

func Reset()

Reset clears the init guard. Tests use this to re-seed the secret; production code must not call it.

CPython: Python/bootstrap_hash.c:L593 _Py_HashRandomization_Fini (adapted from)

Types

type Config

type Config struct {
	UseHashSeed bool
	HashSeed    uint32
}

Config carries the subset of PyConfig that bootstrap_hash.c reads. The full PyConfig lands in v0.7 (initconfig).

CPython: Python/bootstrap_hash.c:L553 _Py_HashRandomization_Init (adapted from)

type SecretMode

type SecretMode int

SecretMode classifies how Init resolved the hash secret.

CPython: Python/bootstrap_hash.c:L553 _Py_HashRandomization_Init (adapted from)

const (
	// SecretRandom means the secret was filled from OS entropy.
	SecretRandom SecretMode = iota
	// SecretZeroed means PYTHONHASHSEED=0 was honored: the secret is
	// all zero so hashes are deterministic for debugging.
	SecretZeroed
	// SecretSeeded means PYTHONHASHSEED was a positive integer and the
	// secret was filled deterministically via lcg_urandom.
	SecretSeeded
)

func Init

func Init(cfg *Config) (SecretMode, error)

Init seeds Secret. If cfg is nil, the PYTHONHASHSEED environment variable is consulted. Init is safe to call concurrently; only the first call performs work, matching CPython's _Py_HashSecret_Initialized guard.

CPython: Python/bootstrap_hash.c:L553 _Py_HashRandomization_Init