vrfkey

Documentation

Index

• Variables
• func FieldHash(msg []byte) *big.Int
• func HashToCurve(p kyber.Point, input *big.Int, ordinates func(x *big.Int)) (kyber.Point, error)
• func IsCurveXOrdinate(x *big.Int) bool
• func IsSquare(x *big.Int) bool
• func ProjectiveECAdd(p, q kyber.Point) (x, y, z fieldElt)
• 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
• type EncryptedVRFKey
  • func (e *EncryptedVRFKey) JSON() ([]byte, error)
  • func (e *EncryptedVRFKey) WriteToDisk(path string) error
• type EncryptedVRFKeyExport
• type KeyV2
  • func FromEncryptedJSON(keyJSON []byte, password string) (KeyV2, error)
  • func MustNewV2XXXTestingOnly(k *big.Int) KeyV2
  • func NewV2() (KeyV2, error)
  • func (key KeyV2) GenerateProof(seed *big.Int) (Proof, error)
  • func (key KeyV2) GenerateProofWithNonce(seed, nonce *big.Int) (Proof, error)
  • func (key KeyV2) GoString() string
  • func (key KeyV2) ID() string
  • func (key KeyV2) Raw() Raw
  • func (key KeyV2) String() string
  • func (key KeyV2) ToEncryptedJSON(password string, scryptParams utils.ScryptParams) (export []byte, err error)
• type PrivateKey
  • func Decrypt(e EncryptedVRFKey, auth string) (*PrivateKey, error)
  • func (k *PrivateKey) GoString() string
  • func (k *PrivateKey) String() string
  • func (k PrivateKey) ToV2() KeyV2
• type Proof
  • func (p *Proof) String() string
  • func (p *Proof) VerifyVRFProof() (bool, error)
  • func (p *Proof) WellFormed() bool
• type Raw
  • func (raw Raw) GoString() string
  • func (raw Raw) Key() KeyV2
  • func (raw Raw) String() string

Variables

var (
	// FieldSize is number of elements in secp256k1's base field, i.e. GF(FieldSize)
	FieldSize = mustParseBig(
		"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F",
	)
	Secp256k1Curve = &secp256k1.Secp256k1{}
	Generator      = Secp256k1Curve.Point().Base()

	ErrCGammaEqualsSHash = fmt.Errorf("pick a different nonce; c*gamma = s*hash, with this one")

	// RandomOutputHashPrefix is a domain-separation tag for the hash used to
	// compute the final VRF random output
	RandomOutputHashPrefix = common.BigToHash(bm.Three).Bytes()
)

Functions

func FieldHash

func FieldHash(msg []byte) *big.Int

FieldHash hashes xs uniformly into {0, ..., fieldSize-1}. msg is assumed to already be a 256-bit hash

func HashToCurve

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

HashToCurve is a cryptographic hash function which outputs a secp256k1 point, or an error. It passes each candidate x ordinate to ordinates function.

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 ProjectiveECAdd

func ProjectiveECAdd(p, q kyber.Point) (x, y, z fieldElt)

ProjectiveECAdd(px, py, qx, qy) duplicates the calculation in projective coordinates of VRF.sol#projectiveECAdd, so we can reliably get the denominator (i.e, z)

func ScalarFromCurvePoints

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

ScalarFromCurve returns a hash for the curve points. Corresponds to the hash computed in VRF.sol#ScalarFromCurvePoints

func SquareRoot

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

SquareRoot returns a s.t. a^2=x, as long as x is a square

func YSquared

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

YSquared returns x^3+7 mod fieldSize, the right-hand side of the secp256k1 curve equation.

Types

type EncryptedVRFKey

type EncryptedVRFKey struct {
	PublicKey secp256k1.PublicKey
	VRFKey    gethKeyStruct `json:"vrf_key"`
	CreatedAt time.Time     `json:"-"`
	UpdatedAt time.Time     `json:"-"`
	DeletedAt *time.Time    `json:"-"`
}

EncryptedVRFKey contains encrypted private key to be serialized to DB

We could re-use geth's key handling, here, but this makes it much harder to misuse VRF proving keys as ethereum keys or vice versa.

func (*EncryptedVRFKey) JSON

func (e *EncryptedVRFKey) JSON() ([]byte, error)

JSON returns the JSON representation of e, or errors

func (*EncryptedVRFKey) WriteToDisk

func (e *EncryptedVRFKey) WriteToDisk(path string) error

WriteToDisk writes the JSON representation of e to given file path, and ensures the file has appropriate access permissions

type EncryptedVRFKeyExport

type EncryptedVRFKeyExport struct {
	PublicKey secp256k1.PublicKey `json:"PublicKey"`
	VRFKey    gethKeyStruct       `json:"vrf_key"`
}

type KeyV2

type KeyV2 struct {
	PublicKey secp256k1.PublicKey
	// contains filtered or unexported fields
}

func FromEncryptedJSON

func FromEncryptedJSON(keyJSON []byte, password string) (KeyV2, error)

func MustNewV2XXXTestingOnly

func MustNewV2XXXTestingOnly(k *big.Int) KeyV2

func NewV2

func NewV2() (KeyV2, error)

func (KeyV2) GenerateProof

func (key KeyV2) GenerateProof(seed *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

secretKey and seed must be less than secp256k1 group order. (Without this constraint on the seed, the samples and the possible public keys would deviate very slightly from uniform distribution.)

func (KeyV2) GenerateProofWithNonce

func (key KeyV2) GenerateProofWithNonce(seed, nonce *big.Int) (Proof, error)

GenerateProofWithNonce allows external nonce generation for testing purposes

As with signatures, using nonces which are in any way predictable to an adversary will leak your secret key! Most people should use GenerateProof instead.

func (KeyV2) GoString

func (key KeyV2) GoString() string

func (KeyV2) ID

func (key KeyV2) ID() string

func (KeyV2) Raw

func (key KeyV2) Raw() Raw

func (KeyV2) String

func (key KeyV2) String() string

func (KeyV2) ToEncryptedJSON

func (key KeyV2) ToEncryptedJSON(password string, scryptParams utils.ScryptParams) (export []byte, err error)

type PrivateKey

type PrivateKey struct {
	PublicKey secp256k1.PublicKey
	// contains filtered or unexported fields
}

PrivateKey represents the secret used to construct a VRF proof.

Don't serialize directly, use Encrypt method, with user-supplied passphrase. The unencrypted PrivateKey struct should only live in-memory.

Only use it if you absolutely need it (i.e., for a novel crypto protocol.) Implement whatever cryptography you need on this struct, so your callers don't need to know the secret key explicitly. (See, e.g., MarshaledProof.)

func Decrypt

func Decrypt(e EncryptedVRFKey, auth string) (*PrivateKey, error)

Decrypt returns the PrivateKey in e, decrypted via auth, or an error

func (*PrivateKey) GoString

func (k *PrivateKey) GoString() string

GoString reduces the risk of accidentally logging the private key

func (*PrivateKey) String

func (k *PrivateKey) String() string

func (PrivateKey) ToV2

func (k PrivateKey) ToV2() KeyV2

type Proof

type Proof struct {
	PublicKey kyber.Point // secp256k1 public key of private key used in proof
	Gamma     kyber.Point
	C         *big.Int
	S         *big.Int
	Seed      *big.Int // Seed input to verifiable random function
	Output    *big.Int // verifiable random function output;, uniform uint256 sample
}

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, C, S and Seed must be secp256k1Point, and Output must be at most 256 bits. See Proof.WellFormed.

func (*Proof) String

func (p *Proof) String() string

func (*Proof) VerifyVRFProof

func (p *Proof) VerifyVRFProof() (bool, error)

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

func (*Proof) WellFormed

func (p *Proof) WellFormed() bool

WellFormed is true iff p's attributes satisfy basic domain checks

type Raw

type Raw []byte

func (Raw) GoString

func (raw Raw) GoString() string

func (Raw) Key

func (raw Raw) Key() KeyV2

func (Raw) String

func (raw Raw) String() string