From: Sergey Matveev <stargrave@stargrave.org>
Date: Wed, 5 Apr 2023 11:53:17 +0000 (+0300)
Subject: Slightly more endianness documentation
X-Git-Tag: v5.10.0~3
X-Git-Url: http://www.git.cypherpunks.ru/?p=gogost.git;a=commitdiff_plain;h=0ad3c46736ab347028125436c7d8435003969f53

Slightly more endianness documentation
---

diff --git a/gost3410/curve.go b/gost3410/curve.go
index 42b7e46..6cc1135 100644
--- a/gost3410/curve.go
+++ b/gost3410/curve.go
@@ -88,6 +88,8 @@ func NewCurve(p, q, a, b, x, y, e, d, co *big.Int) (*Curve, error) {
 	return &c, nil
 }
 
+// Get the size of the point's coordinate in bytes.
+// 32 for 256-bit curves, 64 for 512-bit ones.
 func (c *Curve) PointSize() int {
 	return pointSize(c.P)
 }
diff --git a/gost3410/private.go b/gost3410/private.go
index 7629563..983d8d2 100644
--- a/gost3410/private.go
+++ b/gost3410/private.go
@@ -28,6 +28,7 @@ type PrivateKey struct {
 	Key *big.Int
 }
 
+// Unmarshal little-endian private key. "raw" must be c.PointSize() length.
 func NewPrivateKey(c *Curve, raw []byte) (*PrivateKey, error) {
 	pointSize := c.PointSize()
 	if len(raw) != pointSize {
@@ -52,8 +53,9 @@ func GenPrivateKey(c *Curve, rand io.Reader) (*PrivateKey, error) {
 	return NewPrivateKey(c, raw)
 }
 
-func (prv *PrivateKey) Raw() []byte {
-	raw := pad(prv.Key.Bytes(), prv.C.PointSize())
+// Marshal little-endian private key. raw will be prv.C.PointSize() length.
+func (prv *PrivateKey) Raw() (raw []byte) {
+	raw = pad(prv.Key.Bytes(), prv.C.PointSize())
 	reverse(raw)
 	return raw
 }
@@ -109,6 +111,7 @@ Retry:
 	), nil
 }
 
+// Sign the digest. opts argument is unused.
 func (prv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error) {
 	return prv.SignDigest(digest, rand)
 }
diff --git a/gost3410/public.go b/gost3410/public.go
index 957293e..d2c01bc 100644
--- a/gost3410/public.go
+++ b/gost3410/public.go
@@ -27,6 +27,7 @@ type PublicKey struct {
 	Y *big.Int
 }
 
+// Unmarshal LE(X)||LE(Y) public key. "raw" must be 2*c.PointSize() length.
 func NewPublicKey(c *Curve, raw []byte) (*PublicKey, error) {
 	pointSize := c.PointSize()
 	key := make([]byte, 2*pointSize)
@@ -43,9 +44,10 @@ func NewPublicKey(c *Curve, raw []byte) (*PublicKey, error) {
 	}, nil
 }
 
-func (pub *PublicKey) Raw() []byte {
+// Marshal LE(X)||LE(Y) public key. raw will be 2*pub.C.PointSize() length.
+func (pub *PublicKey) Raw() (raw []byte) {
 	pointSize := pub.C.PointSize()
-	raw := append(
+	raw = append(
 		pad(pub.Y.Bytes(), pointSize),
 		pad(pub.X.Bytes(), pointSize)...,
 	)
diff --git a/gost3410/ukm.go b/gost3410/ukm.go
index ab6fab6..772b178 100644
--- a/gost3410/ukm.go
+++ b/gost3410/ukm.go
@@ -19,6 +19,7 @@ import (
 	"math/big"
 )
 
+// Unmarshal little-endian UKM value.
 func NewUKM(raw []byte) *big.Int {
 	t := make([]byte, len(raw))
 	for i := 0; i < len(t); i++ {
diff --git a/gost34112012256/hash.go b/gost34112012256/hash.go
index 9d7d83f..bae30fe 100644
--- a/gost34112012256/hash.go
+++ b/gost34112012256/hash.go
@@ -14,7 +14,7 @@
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 // GOST R 34.11-2012 256-bit hash function.
-// RFC 6986.
+// RFC 6986. Big-endian hash output.
 package gost34112012256
 
 import (
diff --git a/gost34112012512/hash.go b/gost34112012512/hash.go
index 9a04c8c..b6f2729 100644
--- a/gost34112012512/hash.go
+++ b/gost34112012512/hash.go
@@ -14,7 +14,7 @@
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 // GOST R 34.11-2012 512-bit hash function.
-// RFC 6986.
+// RFC 6986. Big-endian hash output.
 package gost34112012512
 
 import (