core

README

Core Package

The core package contains a set of primitives, including but not limited to various elliptic curves, hashes, and commitment schemes. These primitives are used internally and can also be used independently on their own externally.

Documentation

Overview

Package core contains a set of primitives, including but not limited to various elliptic curves, hashes, and commitment schemes. These primitives are used internally and can also be used independently on their own externally.

Index

• Constants
• Variables
• func Add(x, y, m *big.Int) (*big.Int, error)
• func AnyNil(values ...*big.Int) bool
• func Commit(msg []byte) (Commitment, *Witness, error)
• func ComputeHMAC(f func() hash.Hash, msg []byte, k []byte) ([]byte, error)
• func ConstantTimeEq(a, b *big.Int) bool
• func ConstantTimeEqByte(a, b *big.Int) byte
• func Exp(x, y, m *big.Int) (*big.Int, error)
• func ExpandMessageXmd(f func() hash.Hash, msg, DST []byte, lenInBytes int) ([]byte, error)
• func FiatShamir(values ...*big.Int) ([]byte, error)
• func GenerateSafePrime(bits uint) (*big.Int, error)
• func Hash(msg []byte, curve elliptic.Curve) (*big.Int, error)
• func I2OSP(b, n int) []byte
• func In(x, m *big.Int) error
• func Inv(x, m *big.Int) (*big.Int, error)
• func Mul(x, y, m *big.Int) (*big.Int, error)
• func Neg(x, m *big.Int) (*big.Int, error)
• func OS2IP(os []byte) *big.Int
• func Open(c Commitment, d Witness) (bool, error)
• func Rand(m *big.Int) (*big.Int, error)
• type Commitment
• type HashField
• type Params
• type Witness
  • func (w Witness) MarshalJSON() ([]byte, error)
  • func (w *Witness) UnmarshalJSON(data []byte) error

Constants

const Size = sha256.Size

Size of random values and hash outputs are determined by our hash function

Variables

var (
	// Zero is additive identity in the set of integers
	Zero = big.NewInt(0)

	// One is the multiplicative identity in the set of integers
	One = big.NewInt(1)

	// Two is the odd prime
	Two = big.NewInt(2)
)

Functions

func Add

func Add(x, y, m *big.Int) (*big.Int, error)

Add (modular addition): z = x+y (modulo m)

func AnyNil

func AnyNil(values ...*big.Int) bool

AnyNil determines if any of values are nil

func Commit

func Commit(msg []byte) (Commitment, *Witness, error)

Commit to a given message. Uses SHA256 as the hash function.

func ComputeHMAC

func ComputeHMAC(f func() hash.Hash, msg []byte, k []byte) ([]byte, error)

ComputeHMAC computes HMAC(hash_fn, msg, key) Takes in a hash function to use for HMAC

func ConstantTimeEq

func ConstantTimeEq(a, b *big.Int) bool

ConstantTimeEq determines if a, b have identical byte serialization and uses the crypto/subtle package to get a constant time comparison over byte representations.

func ConstantTimeEqByte

func ConstantTimeEqByte(a, b *big.Int) byte

ConstantTimeEqByte determines if a, b have identical byte serialization and signs. It uses the crypto/subtle package to get a constant time comparison over byte representations. Return value is a byte which may be useful in bitwise operations. Returns 0x1 if the two values have the identical sign and byte representation; 0x0 otherwise.

func Exp

func Exp(x, y, m *big.Int) (*big.Int, error)

Exp (modular exponentiation): z = x^y (modulo m)

func ExpandMessageXmd

func ExpandMessageXmd(f func() hash.Hash, msg, DST []byte, lenInBytes int) ([]byte, error)

func FiatShamir

func FiatShamir(values ...*big.Int) ([]byte, error)

fiatShamir computes the HKDF over many values iteratively such that each value is hashed separately and based on preceding values

The first value is computed as okm_0 = KDF(f || value) where f is a byte slice of 32 0xFF salt is zero-filled byte slice with length equal to the hash output length info is the protocol name okm is the 32 byte output

The each subsequent iteration is computed by as okm_i = KDF(f_i || value || okm_{i-1}) where f_i = 2^b - 1 - i such that there are 0xFF bytes prior to the value. f_1 changes the first byte to 0xFE, f_2 to 0xFD. The previous okm is appended to the value to provide cryptographic domain separation. See https://signal.org/docs/specifications/x3dh/#cryptographic-notation and https://signal.org/docs/specifications/xeddsa/#hash-functions for more details. This uses the KDF function similar to X3DH for each `value` But changes the key just like XEdDSA where the prefix bytes change by a single bit

func GenerateSafePrime

func GenerateSafePrime(bits uint) (*big.Int, error)

GenerateSafePrime creates a prime number `p` where (`p`-1)/2 is also prime with at least `bits`

func Hash

func Hash(msg []byte, curve elliptic.Curve) (*big.Int, error)

func I2OSP

func I2OSP(b, n int) []byte

func In

func In(x, m *big.Int) error

In determines ring membership before modular reduction: x ∈ Z_m returns nil if 0 ≤ x < m

func Inv

func Inv(x, m *big.Int) (*big.Int, error)

Inv (modular inverse): returns y such that xy = 1 (modulo m).

func Mul

func Mul(x, y, m *big.Int) (*big.Int, error)

Mul (modular multiplication): z = x*y (modulo m)

func Neg

func Neg(x, m *big.Int) (*big.Int, error)

Neg (modular negation): z = -x (modulo m)

func OS2IP

func OS2IP(os []byte) *big.Int

func Open

func Open(c Commitment, d Witness) (bool, error)

Open a commitment and return true if the commitment/decommitment pair are valid. reference: spec.§2.4: Commitment Scheme

func Rand

func Rand(m *big.Int) (*big.Int, error)

Rand generates a cryptographically secure random integer in the range: 1 < r < m.

Types

type Commitment

type Commitment []byte

Commitment to a given message which can be later revealed. This is sent to and held by a verifier until the corresponding witness is provided.

type HashField

type HashField struct {
	// F_p^k
	Order           *big.Int // p^k
	Characteristic  *big.Int // p
	ExtensionDegree *big.Int // k
}

type Params

type Params struct {
	F                 *HashField
	SecurityParameter int
	Hash              func() hash.Hash
	L                 int
}

type Witness

type Witness struct {
	Msg []byte
	// contains filtered or unexported fields
}

Witness is sent to and opened by the verifier. This proves that committed message hasn't been altered by later information.

func (Witness) MarshalJSON

func (w Witness) MarshalJSON() ([]byte, error)

MarshalJSON encodes Witness in JSON

func (*Witness) UnmarshalJSON

func (w *Witness) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes JSON into a Witness struct