kt128

README

kt128

kt128 is a Go implementation of KT128 (KangarooTwelve) as specified in RFC 9861.

KT128 is an extendable-output function (XOF) built on TurboSHAKE128. This package supports incremental writes, arbitrary-length output, customization strings, and optimized tree hashing for large inputs.

Highlights

• Implements KT128 as a streaming hash.XOF.
• Switches to tree mode for messages larger than 8192 bytes.
• Uses optimized assembly on amd64 and arm64.
• Falls back to pure Go on other targets, or with -tags purego.
• Exposes Clone, Reset, Equal, and Pos helpers.

Requirements

• Go 1.26.1 or newer

Install

go get github.com/codahale/kt128

Basic Usage

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/codahale/kt128"
)

func main() {
	h := kt128.New(nil)
	_, _ = h.Write([]byte("hello, world"))

	out := make([]byte, 32)
	_, _ = h.Read(out)

	fmt.Println(hex.EncodeToString(out))
}

Read finalizes the hasher on first use and then continues squeezing output on subsequent calls. Because KT128 is an XOF, you choose the output length by the size of the destination buffer.

Customization

Pass a customization string to New:

message := []byte("hello, world")
h := kt128.New([]byte("example-domain"))
_, _ = h.Write(message)

out := make([]byte, 64)
_, _ = h.Read(out)

Performance Notes

For messages larger than one 8 KiB KT128 chunk, the implementation switches to tree hashing. Leaf compression is processed in parallel:

• amd64: AVX2, with AVX-512 when available (use the kt128_disable_avx512 build tag to disable AVX-512)
• arm64: optimized assembly path
• other targets or purego: scalar fallback

API Notes

• New(c []byte) creates a new hasher with customization string c.
• Write absorbs message bytes.
• Read(dst) squeezes output into dst.
• Clone copies the current state so both hashers can evolve independently.
• Reset clears the hasher for reuse.
• Equal compares two hasher states in constant time.
• Pos returns the number of bytes written so far.

License

Dual-licensed under Apache-2.0 and MIT. See LICENSE-APACHE and LICENSE-MIT.

Documentation

Overview

Package kt128 implements KT128 (KangarooTwelve) as specified in RFC 9861.

KT128 is a tree-hash eXtendable-Output Function (XOF) built on TurboSHAKE128. For messages larger than 8192 bytes, it splits input into chunks and computes leaf chain values in parallel using SIMD-accelerated Keccak permutations.

Index

• Constants
• type Hasher
  • func New() *Hasher
  • func (h *Hasher) BlockSize() int
  • func (h *Hasher) Clone() *Hasher
  • func (h *Hasher) Equal(other *Hasher) int
  • func (h *Hasher) Pos() uint64
  • func (h *Hasher) Read(p []byte) (int, error)
  • func (h *Hasher) Reset()
  • func (h *Hasher) SetCustomizationString(c []byte)
  • func (h *Hasher) Write(p []byte) (int, error)

Constants

const (
	// BlockSize is the KT128 chunk size in bytes.
	BlockSize = 8192
)

Types

type Hasher

type Hasher struct {
	// contains filtered or unexported fields
}

Hasher is an incremental KT128 instance.

func New

func New() *Hasher

New returns a new Hasher.

func (*Hasher) BlockSize

func (h *Hasher) BlockSize() int

func (*Hasher) Clone

func (h *Hasher) Clone() *Hasher

Clone returns an independent copy of the Hasher. The original and clone evolve independently.

func (*Hasher) Equal

func (h *Hasher) Equal(other *Hasher) int

Equal returns 1 if h and other represent identical states, 0 otherwise. The comparison is constant-time with respect to buffered data and the underlying sponge state.

func (*Hasher) Pos

func (h *Hasher) Pos() uint64

Pos returns the total number of bytes written via Write.

func (*Hasher) Read

func (h *Hasher) Read(p []byte) (int, error)

Read squeezes output from the XOF. On the first call, it finalizes absorption with empty customization.

func (*Hasher) Reset

func (h *Hasher) Reset()

Reset resets the Hasher to its initial state.

func (*Hasher) SetCustomizationString

func (h *Hasher) SetCustomizationString(c []byte)

SetCustomizationString sets the customization string for the hasher.

func (*Hasher) Write

func (h *Hasher) Write(p []byte) (int, error)

Write absorbs message bytes. It must not be called after Read or Sum.