keccak

Documentation

Overview

keccak gives a toy implementation of the keccak hash function. It is aimed at helping to test the Wizard implementation of Keccak that we are developping by exposing all the underlying functions.

Index

• Constants
• Variables
• func PadStream(stream []byte) []byte
• type Block
  • func ExtractBlock(stream []byte) (block *Block, remStream []byte)
  • func PaddingBlock(stream []byte) *Block
• type Digest
  • func Hash(stream []byte, maybeTraces ...*PermTraces) (digest Digest)
• type PermTraces
  • func GenerateTrace(streams [][]byte) (t PermTraces)
• type State
  • func (a *State) ApplyKeccakfRound(round int)
  • func (a *State) Chi(b *State)
  • func (state *State) ExtractDigest() Digest
  • func (a *State) Iota(round int)
  • func (a *State) Permute(traces *PermTraces)
  • func (a *State) Pi() (b State)
  • func (a *State) Rho()
  • func (a *State) Theta()
  • func (state *State) XorIn(block *Block, traces *PermTraces)

Constants

const (
	//rate in byte
	Rate = 136
	//output length in byte
	OutputLen = 32
	// domain separator byte of Keccak
	Dsb = byte(0x01)
)

const Dim = 5 // size of the keccak state matrix

Dimension of the keccak state matrix. The State is structured as an array of 5 x 5 uint64.

const NumRound int = 24 // number of rounds in the keccak permutation

Variables

var LR = [Dim][Dim]int{
	{0, 36, 3, 41, 18},
	{1, 44, 10, 45, 2},
	{62, 6, 43, 15, 61},
	{28, 55, 25, 21, 56},
	{27, 20, 39, 8, 14},
}

LR collects the triangular numbers for the \pi and \rho step

var RC = [NumRound]uint64{
	0x0000000000000001,
	0x0000000000008082,
	0x800000000000808A,
	0x8000000080008000,
	0x000000000000808B,
	0x0000000080000001,
	0x8000000080008081,
	0x8000000000008009,
	0x000000000000008A,
	0x0000000000000088,
	0x0000000080008009,
	0x000000008000000A,
	0x000000008000808B,
	0x800000000000008B,
	0x8000000000008089,
	0x8000000000008003,
	0x8000000000008002,
	0x8000000000000080,
	0x000000000000800A,
	0x800000008000000A,
	0x8000000080008081,
	0x8000000000008080,
	0x0000000080000001,
	0x8000000080008008,
}

RC stores the rounds constants for the \iota steps

Functions

func PadStream

func PadStream(stream []byte) []byte

PadStream returns the input stream padded following the specification of keccak

Types

type Block

type Block = [Rate / 8]uint64

Block represents a keccak block

func ExtractBlock

func ExtractBlock(stream []byte) (block *Block, remStream []byte)

ExtractBlock extracts a block from the stream and returns the extracted block. remStream is what has not been assigned to a block. Returns an error if stream is empty.

func PaddingBlock

func PaddingBlock(stream []byte) *Block

PaddingBlock constructs the padding block from a stream whose length is assumed to be smaller then the block length

type Digest

type Digest = [OutputLen]byte

Digest represents the output of a keccak hash

func Hash

func Hash(stream []byte, maybeTraces ...*PermTraces) (digest Digest)

Hash computes the keccak hash of a slice of bytes. The user can optionally pass a PermTraces to which the function will append the generated permutation traces throughout the hashing process.

type PermTraces

type PermTraces struct {
	KeccakFInps []State
	KeccakFOuts []State
	Blocks      []Block
	// indicates whether the current perm is for the first block of a hash?
	IsNewHash  []bool
	HashOutPut []Digest
}

PermTraces represents the traces of the keccakf permutation happening when hashing a long string

func GenerateTrace

func GenerateTrace(streams [][]byte) (t PermTraces)

it generates PermTraces from the given stream.

type State

type State [5][5]uint64

State represents the Keccak state.

The indexing is not made consistent with the following resource https://keccak.team/keccak_specs_summary.html

Namely, State[X][Y] gives the S[X, Y] in the spec.

func (*State) ApplyKeccakfRound

func (a *State) ApplyKeccakfRound(round int)

ApplyKeccakfRound applies one round of the keccakf permutation

func (*State) Chi

func (a *State) Chi(b *State)

Applies the Chi step

A[x,y] = B[x,y] xor ((not B[x+1,y]) and B[x+2,y]), for (x,y) in (0…4,0…4)

func (*State) ExtractDigest

func (state *State) ExtractDigest() Digest

ExtractDigest returns the digest

func (*State) Iota

func (a *State) Iota(round int)

Applies the iota step to the keccak state A[0,0] <- A[0,0] xor RC

func (*State) Permute

func (a *State) Permute(traces *PermTraces)

Permute applies the Keccakf permutation over the state and appends an entry to the PermTraces function.

func (*State) Pi

func (a *State) Pi() (b State)

Applies the \pi steps

func (*State) Rho

func (a *State) Rho()

Applies the \rho and \pi steps

B[y,2*x+3*y] = rot(A[x,y], r[x,y]), for (x,y) in (0…4,0…4)

func (*State) Theta

func (a *State) Theta()

Applies the theta step over the state See https://keccak.team/keccak_specs_summary.html

C[x] = A[x,0] xor A[x,1] xor A[x,2] xor A[x,3] xor A[x,4],   for x in 0…4
D[x] = C[x-1] xor rot(C[x+1],1),                             for x in 0…4
A[x,y] = A[x,y] xor D[x],                           for (x,y) in (0…4,0…4)

func (*State) XorIn

func (state *State) XorIn(block *Block, traces *PermTraces)

Xor the input into the state of the hasher