hash

Documentation

Overview

Package hash provides MiMC hash function defined over implemented curves

This package is kept for backwards compatibility. The recommended way to initialize hash function is to directly use the constructors in the corresponding packages (e.g. ecc/bn254/fr/mimc). Using the direct constructors allows to apply options for altering the hash function behavior (endianness, input splicing etc.) and returns more specific types with additional methods.

See [Importing hash functions] below for more information.

Importing hash functions

The package follows registration pattern for importing hash functions. To import all known hash functions in gnark-crypto, import the github.com/consensys/gnark-crypto/hash/all package in your code. To import only a specific hash, then import the corresponding package directly, e.g. github.com/consensys/gnark-crypto/ecc/bn254/fr/mimc. The import format should be:

import _ "github.com/consensys/gnark-crypto/ecc/bn254/fr/mimc"

Length extension attack

The MiMC hash function is vulnerable to a length extension attack. For example when we have a hash

h = MiMC(k || m)

and we want to hash a new message

m' = m || m2,

we can compute

h' = MiMC(k || m || m2)

without knowing k by computing

h' = MiMC(h || m2).

This is because the MiMC hash function is a simple iterated cipher, and the hash value is the state of the cipher after encrypting the message.

There are several ways to mitigate this attack:

• use a random key for each hash
• use a domain separation tag for different use cases: h = MiMC(k || tag || m)
• use the secret input as last input: h = MiMC(m || k)

In general, inside a circuit the length-extension attack is not a concern as due to the circuit definition the attacker can not append messages to existing hash. But the user has to consider the cases when using a secret key and MiMC in different contexts.

Hash input format

The MiMC hash function is defined over a field. The input to the hash function is a byte slice. The byte slice is interpreted as a sequence of field elements. Due to this interpretation, the input byte slice length must be multiple of the field modulus size. And every secuence of byte slice for a single field element must be strictly less than the field modulus.

See open issues:

• https://github.com/Consensys/gnark-crypto/issues/504
• https://github.com/Consensys/gnark-crypto/issues/485

Index

• func RegisterHash(h Hash, new func() hash.Hash)
• type Hash
  • func (m Hash) Available() bool
  • func (m Hash) New() hash.Hash
  • func (m Hash) Size() int
  • func (m Hash) String() string
• type StateStorer

Functions

func RegisterHash

func RegisterHash(h Hash, new func() hash.Hash)

RegisterHash registers a new hash function constructor. Should be called in the init function of the hash package.

To register all known hash functions in gnark-crypto, import the github.com/consensys/gnark-crypto/hash/all package in your code.

Types

type Hash

type Hash uint

Hash defines an unique identifier for a hash function.

const (
	// MIMC_BN254 is the MiMC hash function for the BN254 curve.
	MIMC_BN254 Hash = iota
	// MIMC_BLS12_381 is the MiMC hash function for the BLS12-381 curve.
	MIMC_BLS12_381
	// MIMC_BLS12_377 is the MiMC hash function for the BLS12-377 curve.
	MIMC_BLS12_377
	// MIMC_BW6_761 is the MiMC hash function for the BW6-761 curve.
	MIMC_BW6_761
	// MIMC_BLS24_315 is the MiMC hash function for the BLS24-315 curve.
	MIMC_BLS24_315
	// MIMC_BLS24_317 is the MiMC hash function for the BLS24-317 curve.
	MIMC_BLS24_317
	// MIMC_BW6_633 is the MiMC hash function for the BW6-633 curve.
	MIMC_BW6_633
)

func (Hash) Available

func (m Hash) Available() bool

Available returns true if the hash function is available.

func (Hash) New

func (m Hash) New() hash.Hash

New initializes the hash function. This is a convenience function which does not allow setting hash-specific options.

func (Hash) Size

func (m Hash) Size() int

Size returns the size of the digest of the corresponding hash function

func (Hash) String

func (m Hash) String() string

String returns the unique identifier of the hash function.

type StateStorer

type StateStorer interface {
	hash.Hash

	// State retrieves the current state of the hash function. Calling this
	// method should not destroy the current state and allow continue the use of
	// the current hasher.
	State() []byte
	// SetState sets the state of the hash function from a previously stored
	// state retrieved using [StateStorer.State] method.
	SetState(state []byte) error
}

StateStorer allows to store and retrieve the state of a hash function.