crypto: more docs

crypto/_testsuite/testsuite.go

@@ -14,6 +14,7 @@ import (
 	"github.com/MetaMask/go-did-it/crypto"
 )
 
+// TestHarness describes a keypair implementation for the test/bench suites to operate on.
 type TestHarness[PubT crypto.PublicKey, PrivT crypto.PrivateKey] struct {
 	Name string
 
@@ -38,6 +39,7 @@ type TestHarness[PubT crypto.PublicKey, PrivT crypto.PrivateKey] struct {
 	SignatureBytesSize  int
 }
 
+// TestSuite runs a set of tests against a keypair implementation.
 func TestSuite[PubT crypto.PublicKey, PrivT crypto.PrivateKey](t *testing.T, harness TestHarness[PubT, PrivT]) {
 	stats := struct {
 		bytesPubSize  int
@@ -337,6 +339,7 @@ func TestSuite[PubT crypto.PublicKey, PrivT crypto.PrivateKey](t *testing.T, har
 	})
 }
 
+// BenchSuite runs a set of benchmarks on a keypair implementation.
 func BenchSuite[PubT crypto.PublicKey, PrivT crypto.PrivateKey](b *testing.B, harness TestHarness[PubT, PrivT]) {
 	b.Run("GenerateKeyPair", func(b *testing.B) {
 		b.ReportAllocs()

crypto/hash.go

@@ -12,6 +12,7 @@ import (
 // As the standard crypto library prohibits from registering additional hash algorithm (like keccak),
 // below is essentially an extension of that mechanism to allow it.
 
+// Hash is similar to crypto.Hash but can be extended with more values.
 type Hash uint
 
 const (
@@ -50,6 +51,7 @@ func (h Hash) HashFunc() Hash {
 	return h
 }
 
+// String returns the name of the hash function.
 func (h Hash) String() string {
 	if h < maxStdHash {
 		return stdcrypto.Hash(h).String()
@@ -75,6 +77,7 @@ func (h Hash) New() hash.Hash {
 	panic("requested hash function #" + strconv.Itoa(int(h)) + " is unavailable")
 }
 
+// ToVarsigHash returns the corresponding varsig.Hash value.
 func (h Hash) ToVarsigHash() varsig.Hash {
 	if h == MD5SHA1 {
 		panic("no multihash/multicodec value exists for MD5+SHA1")
@@ -85,6 +88,7 @@ func (h Hash) ToVarsigHash() varsig.Hash {
 	panic("requested hash #" + strconv.Itoa(int(h)) + " is unavailable")
 }
 
+// FromVarsigHash converts a varsig.Hash value to the corresponding Hash value.
 func FromVarsigHash(h varsig.Hash) Hash {
 	switch h {
 	case varsig.HashMd4:

crypto/jwk/private.go

@@ -15,6 +15,7 @@ import (
 	"github.com/MetaMask/go-did-it/crypto/x25519"
 )
 
+// PrivateJwk is a JWK holding a private key
 type PrivateJwk struct {
 	Privkey crypto.PrivateKey
 }

crypto/jwk/public.go

@@ -19,6 +19,7 @@ import (
 // - https://www.rfc-editor.org/rfc/rfc7517#section-4 (JWK)
 // - https://www.iana.org/assignments/jose/jose.xhtml#web-key-types (key parameters)
 
+// PublicJwk is a JWK holding a public key
 type PublicJwk struct {
 	Pubkey crypto.PublicKey
 }

crypto/options.go

@@ -4,6 +4,7 @@ import (
 	"github.com/ucan-wg/go-varsig"
 )
 
+// SigningOpts contains the resulting signature configuration.
 type SigningOpts struct {
 	hash            Hash
 	payloadEncoding varsig.PayloadEncoding
@@ -14,6 +15,7 @@ type SigningOpts struct {
 	keyLen uint64
 }
 
+// CollectSigningOptions collects the signing options into a SigningOpts.
 func CollectSigningOptions(opts []SigningOption) SigningOpts {
 	res := SigningOpts{}
 	for _, opt := range opts {
@@ -22,6 +24,7 @@ func CollectSigningOptions(opts []SigningOption) SigningOpts {
 	return res
 }
 
+// HashOrDefault returns the hash algorithm to be used for signatures, or the default if not specified.
 func (opts SigningOpts) HashOrDefault(_default Hash) Hash {
 	if opts.hash == 0 {
 		return _default
@@ -29,6 +32,7 @@ func (opts SigningOpts) HashOrDefault(_default Hash) Hash {
 	return opts.hash
 }
 
+// PayloadEncoding returns the encoding used on the message before signing it.
 func (opts SigningOpts) PayloadEncoding() varsig.PayloadEncoding {
 	if opts.payloadEncoding == 0 {
 		return varsig.PayloadEncodingVerbatim
@@ -36,6 +40,7 @@ func (opts SigningOpts) PayloadEncoding() varsig.PayloadEncoding {
 	return opts.payloadEncoding
 }
 
+// VarsigMatch returns true if the given varsig parameters match the signing options.
 func (opts SigningOpts) VarsigMatch(algo varsig.Algorithm, curve uint64, keyLength uint64) bool {
 	// This is relatively ugly, but we get cyclic import otherwise
 	switch opts.algo {