vrfkey

Documentation

Overview

Package vrfkey tracks the secret keys associated with VRF proofs. It is a separate package from ../store to increase encapsulation of the keys, reduce the risk of them leaking, and reduce confusion between VRF keys and ethereum keys.

The three types, PrivateKey (private_key.go), PublicKey (public_key.go) and EncryptedSecretKey (serialzation.go) are all aspects of the one keypair.

The details of the secret key in a keypair should remain private to this package. If you need to access the secret key, you should add a method to PrivateKey which does the crypto requiring it, without leaking the secret. See PrivateKey#MarshaledProof in private_key.go, for an example.

PrivateKey#PublicKey represents the associated public key, and, in the context of a VRF, represents a public commitment to a particular "verifiable random function."

EncryptedSecretKey is used to store a public/private keypair in a database, in encrypted form.

Usage

Call vrfkey.CreateKey() to generate a PrivateKey with cryptographically secure randomness.

Call PrivateKey#Encrypt(passphrase) to create a representation of the key which is encrypted for storage.

Call PrivateKey#MarshaledProof(seed) to generate the VRF proof for the given seed and private key. The proof is marshaled in the format expected by the on-chain verification mechanism in VRF.sol. If you want to know the VRF output independently of the on-chain verification mechanism, you can get it from vrf.UnmarshalSolidityProof(p).Output.

Index

• Constants
• Variables
• type EncryptedSecretKey
  • func (e *EncryptedSecretKey) Decrypt(auth string) (*PrivateKey, error)
  • func (e *EncryptedSecretKey) JSON() ([]byte, error)
  • func (e *EncryptedSecretKey) WriteToDisk(path string) error
• type PrivateKey
  • func CreateKey() (key *PrivateKey)
  • func NewPrivateKeyXXXTestingOnly(k *big.Int) *PrivateKey
  • func (k *PrivateKey) Encrypt(auth string, p ...ScryptParams) (*EncryptedSecretKey, error)
  • func (k *PrivateKey) GoStringer() string
  • func (k *PrivateKey) MarshaledProof(seed *big.Int) (vrf.MarshaledProof, error)
  • func (k *PrivateKey) String() string
• type PublicKey
  • func NewPublicKey(rawKey [CompressedPublicKeyLength]byte) *PublicKey
  • func NewPublicKeyFromHex(hex string) (*PublicKey, error)
  • func (k *PublicKey) Address() common.Address
  • func (k *PublicKey) Hash() (common.Hash, error)
  • func (k PublicKey) MarshalText() ([]byte, error)
  • func (k *PublicKey) MustHash() common.Hash
  • func (k *PublicKey) Point() (kyber.Point, error)
  • func (k *PublicKey) Scan(value interface{}) error
  • func (k *PublicKey) Set(l PublicKey)
  • func (k *PublicKey) SetFromHex(hex string) error
  • func (k *PublicKey) String() string
  • func (k *PublicKey) StringUncompressed() (string, error)
  • func (k *PublicKey) UnmarshalText(text []byte) error
  • func (k PublicKey) Value() (driver.Value, error)
• type ScryptParams

Constants

const CompressedPublicKeyLength = 33

CompressedPublicKeyLength is the length of a secp256k1 public key's x ordinate as a uint256, concatenated with 00 if y is even, 01 if odd.

Variables

var FastScryptParams = ScryptParams{N: 2, P: 1}

FastScryptParams is for use in tests, where you don't want to wear out your CPU with expensive key derivations, do not use it in production, or your encrypted VRF keys will be easy to brute-force!

Types

type EncryptedSecretKey

type EncryptedSecretKey struct {
	PublicKey PublicKey     `gorm:"primary_key;type:varchar(68)"`
	VRFKey    gethKeyStruct `json:"vrf_key" gorm:"type:text"`
}

EncryptedSecretKey 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 (*EncryptedSecretKey) Decrypt

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

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

func (*EncryptedSecretKey) JSON

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

JSON returns the JSON representation of e, or errors

func (*EncryptedSecretKey) WriteToDisk

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

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

type PrivateKey

type PrivateKey struct {
	PublicKey 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 CreateKey

func CreateKey() (key *PrivateKey)

CreateKey makes a new VRF proving key from cryptographically secure entropy

func NewPrivateKeyXXXTestingOnly

func NewPrivateKeyXXXTestingOnly(k *big.Int) *PrivateKey

NewPrivateKeyXXXTestingOnly is for testing purposes only!

func (*PrivateKey) Encrypt

func (k *PrivateKey) Encrypt(auth string, p ...ScryptParams,
) (*EncryptedSecretKey, error)

Encrypt returns the key encrypted with passphrase auth

func (*PrivateKey) GoStringer

func (k *PrivateKey) GoStringer() string

GoStringer reduces the risk of accidentally logging the private key

func (*PrivateKey) MarshaledProof

func (k *PrivateKey) MarshaledProof(seed *big.Int) (vrf.MarshaledProof, error)

k.MarshaledProof(seed) is a VRF proof of randomness using k and seed, in the form required by VRF.sol's randomValueFromVRFProof

func (*PrivateKey) String

func (k *PrivateKey) String() string

String reduces the risk of accidentally logging the private key

type PublicKey

type PublicKey [CompressedPublicKeyLength]byte

PublicKey is a secp256k1 point in compressed format

func NewPublicKey

func NewPublicKey(rawKey [CompressedPublicKeyLength]byte) *PublicKey

NewPublicKey returns the PublicKey corresponding to rawKey

func NewPublicKeyFromHex

func NewPublicKeyFromHex(hex string) (*PublicKey, error)

NewPublicKeyFromHex returns the PublicKey encoded by 0x-hex string hex, or errors

func (*PublicKey) Address

func (k *PublicKey) Address() common.Address

Address returns the Ethereum address of k or 0 if the key is invalid

func (*PublicKey) Hash

func (k *PublicKey) Hash() (common.Hash, error)

Hash returns the solidity Keccak256 hash of k. Corresponds to hashOfKey on VRFCoordinator.

func (PublicKey) MarshalText

func (k PublicKey) MarshalText() ([]byte, error)

MarshalText renders k as a text string

func (*PublicKey) MustHash

func (k *PublicKey) MustHash() common.Hash

MusthHash is like Hash, but panics on error. Useful for testing.

func (*PublicKey) Point

func (k *PublicKey) Point() (kyber.Point, error)

Point returns the secp256k1 point corresponding to k

func (*PublicKey) Scan

func (k *PublicKey) Scan(value interface{}) error

Scan reconstructs a PublicKey from a DB record of it.

func (*PublicKey) Set

func (k *PublicKey) Set(l PublicKey)

Set sets k to the public key represented by l

func (*PublicKey) SetFromHex

func (k *PublicKey) SetFromHex(hex string) error

SetFromHex sets k to the public key represented by hex, which must represent the compressed binary format

func (*PublicKey) String

func (k *PublicKey) String() string

String returns k's binary compressed representation, as 0x-hex

func (*PublicKey) StringUncompressed

func (k *PublicKey) StringUncompressed() (string, error)

String returns k's binary uncompressed representation, as 0x-hex

func (*PublicKey) UnmarshalText

func (k *PublicKey) UnmarshalText(text []byte) error

UnmarshalText reads a PublicKey into k from text, or errors

func (PublicKey) Value

func (k PublicKey) Value() (driver.Value, error)

Value marshals PublicKey to be saved in the DB

type ScryptParams

type ScryptParams struct{ N, P int }