Skip to content

Commit dbf8547

Browse files
armfazharmfazh
committed
Improves documentation of group interface.
1 parent 10a0004 commit dbf8547

File tree

4 files changed

+103
-39
lines changed

4 files changed

+103
-39
lines changed

‎group/group.go

+93-29
Original file line numberDiff line numberDiff line change
@@ -7,67 +7,131 @@ import (
77
"io"
88
)
99

10+
// Params stores the size in bytes of elements and scalars.
1011
type Params struct {
1112
ElementLength uint // Length in bytes of an element.
1213
CompressedElementLength uint // Length in bytes of a compressed element.
1314
ScalarLength uint // Length in bytes of a scalar.
1415
}
1516

16-
// Group represents a prime-order group based on elliptic curves.
17+
// Group represents an additive prime-order group based on elliptic curves.
1718
type Group interface {
1819
Params() *Params // Params returns parameters for the group
20+
// Creates an element of the group set to the identity of the group.
1921
NewElement() Element
22+
// Creates a scalar of the group set to zero.
2023
NewScalar() Scalar
24+
// Creates an element of the group set to the identity of the group.
2125
Identity() Element
26+
// Creates an element of the group set to the generator of the group.
2227
Generator() Element
28+
// Returns a scalar set to the group order.
2329
Order() Scalar
24-
RandomElement(io.Reader) Element
25-
RandomScalar(io.Reader) Scalar
30+
// RandomElement creates an element chosen at random (using randomness
31+
// from rnd) from the set of group elements. Use crypto/rand.Reader as
32+
// a cryptographically secure random number generator
33+
RandomElement(rnd io.Reader) Element
34+
// RandomScalar creates a scalar chosen at random (using randomness
35+
// from rnd) from the set of group scalars. Use crypto/rand.Reader as
36+
// a cryptographically secure random number generator
37+
RandomScalar(rnd io.Reader) Scalar
38+
// RandomNonZeroScalar creates a scalar chosen at random (using randomness
39+
// from rnd) from the set of group scalars. Use crypto/rand.Reader as
40+
// a cryptographically secure random number generator. It is guaranteed
41+
// the scalar is not zero.
2642
RandomNonZeroScalar(io.Reader) Scalar
27-
HashToElement(data, dst []byte) Element
28-
HashToElementNonUniform(b, dst []byte) Element
29-
HashToScalar(data, dst []byte) Scalar
43+
// HashToElement hashes a message (msg) using a domain separation string
44+
// (dst) producing a group element with uniform distribution.
45+
HashToElement(msg, dst []byte) Element
46+
// HashToElementNonUniform hashes a message (msg) using a domain separation
47+
// string (dst) producing a group element with nonuniform distribution.
48+
HashToElementNonUniform(msg, dst []byte) Element
49+
// HashToScalar hashes a message (msg) using a domain separation string
50+
// (dst) producing a group scalar with uniform distribution.
51+
HashToScalar(msg, dst []byte) Scalar
3052
}
3153

32-
// Element represents an abstract element of a prime-order group.
54+
// Element represents an element of a prime-order group.
3355
type Element interface {
56+
// Returns the group that the element belongs to.
3457
Group() Group
35-
Set(Element) Element
58+
// Set the receiver to x, and returns the receiver.
59+
Set(x Element) Element
60+
// Copy returns a new element equal to the receiver.
3661
Copy() Element
62+
// IsIdentity returns true if the receiver is the identity element of the
63+
// group.
3764
IsIdentity() bool
38-
IsEqual(Element) bool
39-
CMov(int, Element) Element
40-
CSelect(int, Element, Element) Element
41-
Add(Element, Element) Element
42-
Dbl(Element) Element
43-
Neg(Element) Element
44-
Mul(Element, Scalar) Element
45-
MulGen(Scalar) Element
65+
// IsEqual returns true if the receiver is equal to x.
66+
IsEqual(x Element) bool
67+
// CMov sets the receiver to x if b=1; the receiver is unmodified if b=0;
68+
// otherwise panics if b is not 0 or 1. In all the cases, it returns the
69+
// receiver.
70+
CMov(b int, x Element) Element
71+
// CSelect sets the receiver to x if b=1; sets the receiver to y if b=0;
72+
// otherwise panics if b is not 0 or 1. In all the cases, it returns the
73+
// receiver.
74+
CSelect(b int, x, y Element) Element
75+
// Add sets the receiver to x + y, and returns the receiver.
76+
Add(x, y Element) Element
77+
// Dbl sets the receiver to 2 * x, and returns the receiver.
78+
Dbl(x Element) Element
79+
// Neg sets the receiver to -x, and returns the receiver.
80+
Neg(x Element) Element
81+
// Mul sets the receiver to s * x, and returns the receiver.
82+
Mul(x Element, s Scalar) Element
83+
// MulGen sets the receiver to s * Generator(), and returns the receiver.
84+
MulGen(s Scalar) Element
85+
// BinaryMarshaler returns a byte representation of the element.
4686
encoding.BinaryMarshaler
87+
// BinaryUnmarshaler recovers an element from a byte representation
88+
// produced either by encoding.BinaryMarshaler or MarshalBinaryCompress.
4789
encoding.BinaryUnmarshaler
90+
// MarshalBinaryCompress returns a byte representation of an elment in a
91+
// compact form whenever the group supports it; otherwise, returns the
92+
// same byte representation produced by encoding.BinaryMarshaler.
4893
MarshalBinaryCompress() ([]byte, error)
4994
}
5095

51-
// Scalar represents an integer scalar.
96+
// Scalar represents a scalar of a prime-order group.
5297
type Scalar interface {
98+
// Returns the group that the scalar belongs to.
5399
Group() Group
54-
Set(Scalar) Scalar
100+
// Set the receiver to x, and returns the receiver.
101+
Set(x Scalar) Scalar
102+
// Copy returns a new scalar equal to the receiver.
55103
Copy() Scalar
56-
IsEqual(Scalar) bool
57-
SetUint64(uint64)
58-
CMov(int, Scalar) Scalar
59-
CSelect(int, Scalar, Scalar) Scalar
60-
Add(Scalar, Scalar) Scalar
61-
Sub(Scalar, Scalar) Scalar
62-
Mul(Scalar, Scalar) Scalar
63-
Neg(Scalar) Scalar
64-
Inv(Scalar) Scalar
104+
// IsEqual returns true if the receiver is equal to x.
105+
IsEqual(x Scalar) bool
106+
// SetUint64 set the receiver to x, and returns the receiver.
107+
SetUint64(x uint64) Scalar
108+
// CMov sets the receiver to x if b=1; the receiver is unmodified if b=0;
109+
// otherwise panics if b is not 0 or 1. In all the cases, it returns the
110+
// receiver.
111+
CMov(b int, x Scalar) Scalar
112+
// CSelect sets the receiver to x if b=1; sets the receiver to y if b=0;
113+
// otherwise panics if b is not 0 or 1. In all the cases, it returns the
114+
// receiver.
115+
CSelect(b int, x, y Scalar) Scalar
116+
// Add sets the receiver to x + y, and returns the receiver.
117+
Add(x, y Scalar) Scalar
118+
// Sub sets the receiver to x - y, and returns the receiver.
119+
Sub(x, y Scalar) Scalar
120+
// Mul sets the receiver to x * y, and returns the receiver.
121+
Mul(x, y Scalar) Scalar
122+
// Neg sets the receiver to -x, and returns the receiver.
123+
Neg(x Scalar) Scalar
124+
// Inv sets the receiver to 1/x, and returns the receiver.
125+
Inv(x Scalar) Scalar
126+
// BinaryMarshaler returns a byte representation of the scalar.
65127
encoding.BinaryMarshaler
128+
// BinaryUnmarshaler recovers a scalar from a byte representation produced
129+
// by encoding.BinaryMarshaler.
66130
encoding.BinaryUnmarshaler
67131
}
68132

69133
var (
70-
ErrType = errors.New("type mismatch")
71-
ErrUnmarshal = errors.New("error unmarshaling")
134+
ErrType = errors.New("group: type mismatch")
135+
ErrUnmarshal = errors.New("group: error unmarshaling")
72136
ErrSelector = errors.New("group: selector must be 0 or 1")
73137
)

‎group/group_test.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -145,9 +145,9 @@ func testCSelect(t *testing.T, testTimes int, g group.Group) {
145145
test.CheckNoErr(t, err, "should fail with dif 0,1")
146146

147147
for i := 0; i < testTimes; i++ {
148-
P := g.RandomElement(rand.Reader)
149-
Q := g.RandomElement(rand.Reader)
150-
R := g.RandomElement(rand.Reader)
148+
P = g.RandomElement(rand.Reader)
149+
Q = g.RandomElement(rand.Reader)
150+
R = g.RandomElement(rand.Reader)
151151

152152
want := R.Copy()
153153
got := P.CSelect(0, Q, R)

‎group/ristretto255.go

+4-4
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import (
1010
"github.com/cloudflare/circl/expander"
1111
)
1212

13-
// Ristretto255 is a quotient group generated from edwards25519 curve.
13+
// Ristretto255 is a quotient group generated from the edwards25519 curve.
1414
var Ristretto255 Group = ristrettoGroup{}
1515

1616
type ristrettoGroup struct{}
@@ -202,9 +202,9 @@ func (e *ristrettoElement) UnmarshalBinary(data []byte) error {
202202
return e.p.UnmarshalBinary(data)
203203
}
204204

205-
func (s *ristrettoScalar) Group() Group { return Ristretto255 }
206-
func (s *ristrettoScalar) String() string { return fmt.Sprintf("0x%x", s.s.Bytes()) }
207-
func (s *ristrettoScalar) SetUint64(n uint64) { s.s.SetUint64(n) }
205+
func (s *ristrettoScalar) Group() Group { return Ristretto255 }
206+
func (s *ristrettoScalar) String() string { return fmt.Sprintf("0x%x", s.s.Bytes()) }
207+
func (s *ristrettoScalar) SetUint64(n uint64) Scalar { s.s.SetUint64(n); return s }
208208

209209
func (s *ristrettoScalar) IsEqual(x Scalar) bool {
210210
return s.s.Equals(&x.(*ristrettoScalar).s)

‎group/short.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -271,9 +271,9 @@ type wScl struct {
271271
k []byte
272272
}
273273

274-
func (s *wScl) Group() Group { return s.wG }
275-
func (s *wScl) String() string { return fmt.Sprintf("0x%x", s.k) }
276-
func (s *wScl) SetUint64(n uint64) { s.fromBig(new(big.Int).SetUint64(n)) }
274+
func (s *wScl) Group() Group { return s.wG }
275+
func (s *wScl) String() string { return fmt.Sprintf("0x%x", s.k) }
276+
func (s *wScl) SetUint64(n uint64) Scalar { s.fromBig(new(big.Int).SetUint64(n)); return s }
277277
func (s *wScl) IsEqual(a Scalar) bool {
278278
aa := s.cvtScl(a)
279279
return subtle.ConstantTimeCompare(s.k, aa.k) == 1

0 commit comments

Comments
 (0)