1 // Package group provides prime-order groups based on elliptic curves. 2 package group 3 4 import ( 5 "encoding" 6 "errors" 7 "io" 8 "math/big" 9 ) 10 11 // Params stores the size in bytes of elements and scalars. 12 type Params struct { 13 ElementLength uint // Length in bytes of an element. 14 CompressedElementLength uint // Length in bytes of a compressed element. 15 ScalarLength uint // Length in bytes of a scalar. 16 } 17 18 // Group represents an additive prime-order group based on elliptic curves. 19 type Group interface { 20 Params() *Params // Params returns parameters for the group 21 // Creates an element of the group set to the identity of the group. 22 NewElement() Element 23 // Creates a scalar of the group set to zero. 24 NewScalar() Scalar 25 // Creates an element of the group set to the identity of the group. 26 Identity() Element 27 // Creates an element of the group set to the generator of the group. 28 Generator() Element 29 // Returns a scalar set to the group order. 30 Order() Scalar 31 // RandomElement creates an element chosen at random (using randomness 32 // from rnd) from the set of group elements. Use crypto/rand.Reader as 33 // a cryptographically secure random number generator 34 RandomElement(rnd io.Reader) Element 35 // RandomScalar creates a scalar chosen at random (using randomness 36 // from rnd) from the set of group scalars. Use crypto/rand.Reader as 37 // a cryptographically secure random number generator 38 RandomScalar(rnd io.Reader) Scalar 39 // RandomNonZeroScalar creates a scalar chosen at random (using randomness 40 // from rnd) from the set of group scalars. Use crypto/rand.Reader as 41 // a cryptographically secure random number generator. It is guaranteed 42 // the scalar is not zero. 43 RandomNonZeroScalar(io.Reader) Scalar 44 // HashToElement hashes a message (msg) using a domain separation string 45 // (dst) producing a group element with uniform distribution. 46 HashToElement(msg, dst []byte) Element 47 // HashToElementNonUniform hashes a message (msg) using a domain separation 48 // string (dst) producing a group element with nonuniform distribution. 49 HashToElementNonUniform(msg, dst []byte) Element 50 // HashToScalar hashes a message (msg) using a domain separation string 51 // (dst) producing a group scalar with uniform distribution. 52 HashToScalar(msg, dst []byte) Scalar 53 } 54 55 // Element represents an element of a prime-order group. 56 type Element interface { 57 // Returns the group that the element belongs to. 58 Group() Group 59 // Set the receiver to x, and returns the receiver. 60 Set(x Element) Element 61 // Copy returns a new element equal to the receiver. 62 Copy() Element 63 // IsIdentity returns true if the receiver is the identity element of the 64 // group. 65 IsIdentity() bool 66 // IsEqual returns true if the receiver is equal to x. 67 IsEqual(x Element) bool 68 // CMov sets the receiver to x if b=1; the receiver is unmodified if b=0; 69 // otherwise panics if b is not 0 or 1. In all the cases, it returns the 70 // receiver. 71 CMov(b int, x Element) Element 72 // CSelect sets the receiver to x if b=1; sets the receiver to y if b=0; 73 // otherwise panics if b is not 0 or 1. In all the cases, it returns the 74 // receiver. 75 CSelect(b int, x, y Element) Element 76 // Add sets the receiver to x + y, and returns the receiver. 77 Add(x, y Element) Element 78 // Dbl sets the receiver to 2 * x, and returns the receiver. 79 Dbl(x Element) Element 80 // Neg sets the receiver to -x, and returns the receiver. 81 Neg(x Element) Element 82 // Mul sets the receiver to s * x, and returns the receiver. 83 Mul(x Element, s Scalar) Element 84 // MulGen sets the receiver to s * Generator(), and returns the receiver. 85 MulGen(s Scalar) Element 86 // BinaryMarshaler returns a byte representation of the element. 87 encoding.BinaryMarshaler 88 // BinaryUnmarshaler recovers an element from a byte representation 89 // produced either by encoding.BinaryMarshaler or MarshalBinaryCompress. 90 encoding.BinaryUnmarshaler 91 // MarshalBinaryCompress returns a byte representation of an element in a 92 // compact form whenever the group supports it; otherwise, returns the 93 // same byte representation produced by encoding.BinaryMarshaler. 94 MarshalBinaryCompress() ([]byte, error) 95 } 96 97 // Scalar represents a scalar of a prime-order group. 98 type Scalar interface { 99 // Returns the group that the scalar belongs to. 100 Group() Group 101 // Set the receiver to x, and returns the receiver. 102 Set(x Scalar) Scalar 103 // Copy returns a new scalar equal to the receiver. 104 Copy() Scalar 105 // IsZero returns true if the receiver is equal to zero. 106 IsZero() bool 107 // IsEqual returns true if the receiver is equal to x. 108 IsEqual(x Scalar) bool 109 // SetUint64 sets the receiver to x, and returns the receiver. 110 SetUint64(x uint64) Scalar 111 // SetBigInt sets the receiver to x, and returns the receiver. 112 // Warning: operations on big.Int are not constant time. Do not use them 113 // for cryptography unless you're sure it's safe in your use-case. 114 SetBigInt(b *big.Int) Scalar 115 // CMov sets the receiver to x if b=1; the receiver is unmodified if b=0; 116 // otherwise panics if b is not 0 or 1. In all the cases, it returns the 117 // receiver. 118 CMov(b int, x Scalar) Scalar 119 // CSelect sets the receiver to x if b=1; sets the receiver to y if b=0; 120 // otherwise panics if b is not 0 or 1. In all the cases, it returns the 121 // receiver. 122 CSelect(b int, x, y Scalar) Scalar 123 // Add sets the receiver to x + y, and returns the receiver. 124 Add(x, y Scalar) Scalar 125 // Sub sets the receiver to x - y, and returns the receiver. 126 Sub(x, y Scalar) Scalar 127 // Mul sets the receiver to x * y, and returns the receiver. 128 Mul(x, y Scalar) Scalar 129 // Neg sets the receiver to -x, and returns the receiver. 130 Neg(x Scalar) Scalar 131 // Inv sets the receiver to 1/x, and returns the receiver. 132 Inv(x Scalar) Scalar 133 // BinaryMarshaler returns a byte representation of the scalar. 134 encoding.BinaryMarshaler 135 // BinaryUnmarshaler recovers a scalar from a byte representation produced 136 // by encoding.BinaryMarshaler. 137 encoding.BinaryUnmarshaler 138 } 139 140 var ( 141 ErrType = errors.New("group: type mismatch") 142 ErrUnmarshal = errors.New("group: error unmarshaling") 143 ErrSelector = errors.New("group: selector must be 0 or 1") 144 ) 145