vrf

Documentation

Overview

Package vrf provides a cryptographically secure pseudo-random number generator. //////////////////////////////////////////////////////////////////////////////

XXX: Do not use in production until this code has been audited.

////////////////////////////////////////////////////////////////////////////// Numbers are deterministically generated from a seed and a secret key, and are statistically indistinguishable from uniform sampling from {0, ..., 2**256}, to observers who don't know the key. But each number comes with a proof that it was generated according to the procedure mandated by a public key associated with that private key.

See VRF.sol for design notes.

Usage -----

A secret key sk should be securely sampled uniformly from {0, ..., Order}. The public key associated with it can be calculated from it by XXX

To generate random output from a big.Int seed, pass sk and the seed to GenerateProof, and use the Output field of the returned Proof object.

To verify a Proof object p, run p.Verify(), or pass its fields to the corresponding arguments of isValidVRFOutput on the VRF solidity contract, to verify it on-chain.

Index

• Variables
• func CoordsFromPoint(p kyber.Point) (*big.Int, *big.Int)
• func HashToCurve(p kyber.Point, input *big.Int) (kyber.Point, error)
• func HashUint256s(xs ...*big.Int) (*big.Int, error)
• func IsCurveXOrdinate(x *big.Int) bool
• func IsSquare(x *big.Int) bool
• func ScalarFromCurvePoints(hash, pk, gamma kyber.Point, uWitness [20]byte, v kyber.Point) *big.Int
• func SquareRoot(x *big.Int) *big.Int
• func YSquared(x *big.Int) *big.Int
• func ZqHash(q *big.Int, msg []byte) (*big.Int, error)
• type Proof
  • func GenerateProof(secretKey, seed, nonce *big.Int) (*Proof, error)
  • func (proof *Proof) Verify() (bool, error)
  • func (p *Proof) WellFormed() bool

Variables

var Generator = rcurve.Point().Base()

Generator is a specific generator of the curve group. Any non-zero point will do, since the group order is prime. But one must be specified as part of the protocol.

var Order = bigFromHex(
	"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141")

Order is the number of rational points on the curve in GF(P) (group size)

var P = bigFromHex(
	"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F")

P is number of elements in the Galois field over which secp256k1 is defined

Functions

func CoordsFromPoint

func CoordsFromPoint(p kyber.Point) (*big.Int, *big.Int)

CoordsFromPoint returns the (x, y) coordinates of p

func HashToCurve

func HashToCurve(p kyber.Point, input *big.Int) (kyber.Point, error)

HashToCurve is a one-way hash function onto the curve

func HashUint256s

func HashUint256s(xs ...*big.Int) (*big.Int, error)

HashUint256s returns a uint256 representing the hash of the concatenated byte representations of the inputs

func IsCurveXOrdinate

func IsCurveXOrdinate(x *big.Int) bool

IsCurveXOrdinate returns true iff there is y s.t. y^2=x^3+7

func IsSquare

func IsSquare(x *big.Int) bool

IsSquare returns true iff x = y^2 for some y in GF(p)

func ScalarFromCurvePoints

func ScalarFromCurvePoints(
	hash, pk, gamma kyber.Point, uWitness [20]byte, v kyber.Point) *big.Int

ScalarFromCurvePoints returns a hash for the curve points. Corresponds to the hash computed in Curve.sol#scalarFromCurve

func SquareRoot

func SquareRoot(x *big.Int) *big.Int

SquareRoot returns a s.t. a^2=x. Assumes x is a square

func YSquared

func YSquared(x *big.Int) *big.Int

YSquared returns x^3+7 mod P

func ZqHash

func ZqHash(q *big.Int, msg []byte) (*big.Int, error)

ZqHash hashes xs uniformly into {0, ..., q-1}. q must be 256 bits long, and msg is assumed to already be a 256-bit hash

Types

type Proof

type Proof struct {
	PublicKey, Gamma   kyber.Point
	C, S, Seed, Output *big.Int
}

Proof represents a proof that Gamma was constructed from the Seed according to the process mandated by the PublicKey.

N.B.: The kyber.Point fields must contain secp256k1.secp256k1Point values

func GenerateProof

func GenerateProof(secretKey, seed, nonce *big.Int) (*Proof, error)

GenerateProof returns gamma, plus proof that gamma was constructed from seed as mandated from the given secretKey, with public key secretKey*Generator Proof is constructed using nonce as the ephemeral key. If provided, it must be treated as key material (cryptographically-securely randomly generated, kept confidential or just forgotten.) If it's nil, it will be generated here.

func (*Proof) Verify

func (proof *Proof) Verify() (bool, error)

VerifyProof is true iff gamma was generated in the mandated way from the given publicKey and seed

func (*Proof) WellFormed

func (p *Proof) WellFormed() bool