Changes after rozbb review.

Author: armfazh

README.md

@@ -38,6 +38,7 @@ Alternatively, look at the [Cloudflare Go](https://github.com/cloudflare/go/tree
 [RFC-9496]: https://doi.org/10.17487/RFC9496
 [RFC-9497]: https://doi.org/10.17487/RFC9497
 [FIPS 202]: https://doi.org/10.6028/NIST.FIPS.202
+[FIPS 204]: https://doi.org/10.6028/NIST.FIPS.204
 [FIPS 205]: https://doi.org/10.6028/NIST.FIPS.205
 [FIPS 186-5]: https://doi.org/10.6028/NIST.FIPS.186-5
 [BLS12-381]: https://electriccoin.co/blog/new-snark-curve/
@@ -92,7 +93,7 @@ Alternatively, look at the [Cloudflare Go](https://github.com/cloudflare/go/tree
 |:---:|
 
  - [Dilithium](./sign/dilithium): modes 2, 3, 5 ([Dilithium](https://pq-crystals.org/dilithium/)).
- - [ML-DSA](./sign/mldsa): modes 44, 65, 87 ([FIPS 204](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf)).
+ - [ML-DSA](./sign/mldsa): modes 44, 65, 87 ([FIPS 204]).
  - [SLH-DSA](./sign/slhdsa): twelve parameter sets, pure and pre-hash signing ([FIPS 205]).
 
 ### Zero-knowledge Proofs

sign/schemes/schemes.go

@@ -6,23 +6,26 @@
 //	Ed448
 //	Ed25519-Dilithium2
 //	Ed448-Dilithium3
+//	Dilithium
+//	ML-DSA
+//	SLH-DSA
 package schemes
 
 import (
 	"strings"
 
 	"github.com/cloudflare/circl/sign"
+	dilithium2 "github.com/cloudflare/circl/sign/dilithium/mode2"
+	dilithium3 "github.com/cloudflare/circl/sign/dilithium/mode3"
+	dilithium5 "github.com/cloudflare/circl/sign/dilithium/mode5"
 	"github.com/cloudflare/circl/sign/ed25519"
 	"github.com/cloudflare/circl/sign/ed448"
 	"github.com/cloudflare/circl/sign/eddilithium2"
 	"github.com/cloudflare/circl/sign/eddilithium3"
-	"github.com/cloudflare/circl/sign/slhdsa"
-	dilithium2 "github.com/cloudflare/circl/sign/dilithium/mode2"
-	dilithium3 "github.com/cloudflare/circl/sign/dilithium/mode3"
-	dilithium5 "github.com/cloudflare/circl/sign/dilithium/mode5"
 	"github.com/cloudflare/circl/sign/mldsa/mldsa44"
 	"github.com/cloudflare/circl/sign/mldsa/mldsa65"
 	"github.com/cloudflare/circl/sign/mldsa/mldsa87"
+	"github.com/cloudflare/circl/sign/slhdsa"
 )
 
 var allSchemes = [...]sign.Scheme{

sign/slhdsa/acvp_test.go

@@ -180,8 +180,6 @@ func testVerify(t *testing.T) {
 }
 
 func acvpKeygen(t *testing.T, paramSet string, in *keygenInput) {
-	t.Parallel()
-
 	id, err := ParamIDByName(paramSet)
 	test.CheckNoErr(t, err, "invalid param name")
 
@@ -226,8 +224,6 @@ func acvpSign(
 	wantSignature []byte,
 	deterministic bool,
 ) {
-	t.Parallel()
-
 	id, err := ParamIDByName(paramSet)
 	test.CheckNoErr(t, err, "invalid param name")
 

sign/slhdsa/all_test.go

@@ -11,8 +11,6 @@ func TestInner(t *testing.T) {
 		param := &supportedParams[i]
 
 		t.Run(param.name, func(t *testing.T) {
-			t.Parallel()
-
 			t.Run("Wots", func(t *testing.T) { testWotsPlus(t, param) })
 			t.Run("Xmss", func(t *testing.T) { testXmss(t, param) })
 			t.Run("Ht", func(tt *testing.T) { testHyperTree(tt, param) })

sign/slhdsa/fors.go

@@ -46,6 +46,10 @@ func (s *statePriv) forsSkGen(addr address, idx uint32) forsPrivateKey {
 }
 
 // See FIPS 205 -- Section 8.2 -- Algorithm 15 -- Iterative version.
+//
+// This is a stack-based implementation that computes the tree leaves
+// in order (from the left to the right).
+// Its recursive version can be found at fors_test.go file.
 func (s *statePriv) forsNodeIter(
 	stack stackNode, root []byte, i, z uint32, addr address,
 ) {
@@ -103,7 +107,8 @@ func (s *statePriv) forsSign(sig forsSignature, digest []byte, addr address) {
 
 		bits -= s.a
 		indicesI := (total >> bits) & maskA
-		forsSk := s.forsSkGen(addr, (i<<s.a)+indicesI)
+		treeIdx := (i << s.a) + indicesI
+		forsSk := s.forsSkGen(addr, treeIdx)
 		copy(sig[i].sk, forsSk)
 
 		for j := uint32(0); j < s.a; j++ {
@@ -115,7 +120,7 @@ func (s *statePriv) forsSign(sig forsSignature, digest []byte, addr address) {
 
 // See FIPS 205 -- Section 8.4 -- Algorithm 17.
 func (s *state) forsPkFromSig(
-	digest []byte, sig forsSignature, addr address,
+	sig forsSignature, digest []byte, addr address,
 ) (pk forsPublicKey) {
 	pk = make([]byte, s.forsPkSize())
 
@@ -130,7 +135,7 @@ func (s *state) forsPkFromSig(
 	s.T.Reset()
 
 	in, bits, total := 0, uint32(0), uint32(0)
-	maskB := (uint32(1) << s.a) - 1
+	maskA := (uint32(1) << s.a) - 1
 
 	for i := uint32(0); i < s.k; i++ {
 		for bits < s.a {
@@ -140,7 +145,7 @@ func (s *state) forsPkFromSig(
 		}
 
 		bits -= s.a
-		indicesI := (total >> bits) & maskB
+		indicesI := (total >> bits) & maskA
 		treeIdx := (i << s.a) + indicesI
 		s.F.address.SetTreeIndex(treeIdx)
 		s.F.SetMessage(sig[i].sk)

sign/slhdsa/fors_test.go

@@ -65,8 +65,7 @@ func testFors(t *testing.T, p *params) {
 	curSig := cursor(make([]byte, p.forsSigSize()))
 	sig.fromBytes(p, &curSig)
 	state.forsSign(sig, msg, addr)
-
-	pkFors := state.forsPkFromSig(msg, sig, addr)
+	pkFors := state.forsPkFromSig(sig, msg, addr)
 
 	var htSig hyperTreeSignature
 	curHtSig := cursor(make([]byte, p.hyperTreeSigSize()))
@@ -111,7 +110,7 @@ func benchmarkFors(b *testing.B, p *params) {
 	})
 	b.Run("PkFromSig", func(b *testing.B) {
 		for i := 0; i < b.N; i++ {
-			_ = state.forsPkFromSig(msg, sig, addr)
+			_ = state.forsPkFromSig(sig, msg, addr)
 		}
 	})
 }

sign/slhdsa/internal.go

@@ -86,7 +86,7 @@ func slhSignInternal(
 	defer s.Clear()
 
 	s.forsSign(sig.forsSig, md, addr)
-	pkFors := s.forsPkFromSig(md, sig.forsSig, addr)
+	pkFors := s.forsPkFromSig(sig.forsSig, md, addr)
 	s.htSign(sig.htSig, pkFors, idxTree, idxLeaf)
 
 	return sigBytes, nil
@@ -114,7 +114,7 @@ func slhVerifyInternal(
 	s := p.NewStatePub(pub.seed)
 	defer s.Clear()
 
-	pkFors := s.forsPkFromSig(md, sig.forsSig, addr)
+	pkFors := s.forsPkFromSig(sig.forsSig, md, addr)
 	return s.htVerify(pkFors, pub.root, idxTree, idxLeaf, sig.htSig)
 }
 

sign/slhdsa/slhdsa.go

@@ -274,6 +274,7 @@ func readRandom(random io.Reader, size uint32) (out []byte, err error) {
 
 var (
 	ErrContext  = fmt.Errorf("sign/slhdsa: context is larger than MaxContextSize=%v bytes", MaxContextSize)
+	ErrMsgLen   = errors.New("sign/slhdsa: invalid message length")
 	ErrParam    = errors.New("sign/slhdsa: invalid SLH-DSA parameter")
 	ErrPreHash  = errors.New("sign/slhdsa: invalid prehash function")
 	ErrSigParse = errors.New("sign/slhdsa: failed to decode the signature")

sign/slhdsa/slhdsa_test.go

@@ -37,8 +37,6 @@ func TestSlhdsa(t *testing.T) {
 		id := supportedParameters[i]
 
 		t.Run(id.Name(), func(t *testing.T) {
-			t.Parallel()
-
 			t.Run("Keys", func(t *testing.T) { testKeys(t, id) })
 
 			for j := range supportedPrehashIDs {

sign/slhdsa/wotsp.go

@@ -22,10 +22,10 @@ func (ws *wotsSignature) fromBytes(p *params, c *cursor) {
 }
 
 // See FIPS 205 -- Section 5 -- Algorithm 5.
-func (s *state) chain(x []byte, index, step uint32, addr address) (out []byte) {
+func (s *state) chain(x []byte, index, steps uint32, addr address) (out []byte) {
 	out = x
 	s.F.address.Set(addr)
-	for j := index; j < index+step; j++ {
+	for j := index; j < index+steps; j++ {
 		s.F.address.SetHashAddress(j)
 		s.F.SetMessage(out)
 		out = s.F.Final()
@@ -60,6 +60,10 @@ func (s *statePriv) wotsPkGen(addr address) wotsPublicKey {
 
 // See FIPS 205 -- Section 5.2 -- Algorithm 7.
 func (s *statePriv) wotsSign(sig wotsSignature, msg []byte, addr address) {
+	if len(msg) != int(s.wotsLen1()/2) {
+		panic(ErrMsgLen)
+	}
+
 	curSig := cursor(sig)
 	wotsLen1 := s.wotsLen1()
 	csum := wotsLen1 * (wotsW - 1)
@@ -68,6 +72,7 @@ func (s *statePriv) wotsSign(sig wotsSignature, msg []byte, addr address) {
 	s.PRF.address.SetTypeAndClear(addressWotsPrf)
 	s.PRF.address.SetKeyPairAddress(addr.GetKeyPairAddress())
 
+	// Signs every nibble of the message and computes the checksum.
 	for i := uint32(0); i < wotsLen1; i++ {
 		s.PRF.address.SetChainAddress(i)
 		sk := s.PRF.Final()
@@ -79,6 +84,7 @@ func (s *statePriv) wotsSign(sig wotsSignature, msg []byte, addr address) {
 		csum -= msgi
 	}
 
+	// Lastly, every nibble of the checksum is also signed.
 	for i := uint32(0); i < wotsLen2; i++ {
 		s.PRF.address.SetChainAddress(wotsLen1 + i)
 		sk := s.PRF.Final()
@@ -94,6 +100,10 @@ func (s *statePriv) wotsSign(sig wotsSignature, msg []byte, addr address) {
 func (s *state) wotsPkFromSig(
 	sig wotsSignature, msg []byte, addr address,
 ) wotsPublicKey {
+	if len(msg) != int(s.wotsLen1()/2) {
+		panic(ErrMsgLen)
+	}
+
 	wotsLen1 := s.wotsLen1()
 	csum := wotsLen1 * (wotsW - 1)
 
@@ -104,6 +114,8 @@ func (s *state) wotsPkFromSig(
 	s.T.Reset()
 	curSig := cursor(sig)
 
+	// Signs every nibble of the message, computes the checksum, and
+	// feeds each signature to the T function.
 	for i := uint32(0); i < wotsLen1; i++ {
 		addr.SetChainAddress(i)
 		msgi := uint32((msg[i/2] >> ((1 - (i & 1)) << 2)) & 0xF)
@@ -113,6 +125,8 @@ func (s *state) wotsPkFromSig(
 		csum -= msgi
 	}
 
+	// Every nibble of the checksum is also signed feeding the signature
+	// to the T function.
 	for i := uint32(0); i < wotsLen2; i++ {
 		addr.SetChainAddress(wotsLen1 + i)
 		csumi := (csum >> (8 - 4*i)) & 0xF
@@ -121,5 +135,6 @@ func (s *state) wotsPkFromSig(
 		s.T.WriteMessage(sigi)
 	}
 
+	// Generates the public key as the output of the T function.
 	return s.T.Final()
 }

sign/slhdsa/xmss.go

@@ -24,6 +24,10 @@ func (xs *xmssSignature) fromBytes(p *params, c *cursor) {
 }
 
 // See FIPS 205 -- Section 6.1 -- Algorithm 9 -- Iterative version.
+//
+// This is a stack-based implementation that computes the tree leaves
+// in order (from the left to the right).
+// Its recursive version can be found at xmss_test.go file.
 func (s *statePriv) xmssNodeIter(
 	stack stackNode, root []byte, i, z uint32, addr address,
 ) {