Documentation cleanup

README.md

@@ -44,15 +44,15 @@ privateKey, _ := ecdsa.GenerateKey(elliptic.P521(), rand.Reader)
 signer, _ := cose.NewSigner(cose.AlgorithmES512, privateKey)
 
 // create message to be signed
-msg := cose.NewSign1Message()
+msgToSign := cose.NewSign1Message()
 msgToSign.Payload = []byte("hello world")
-msg.Headers.Protected.SetAlgorithm(cose.AlgorithmES512)
+msgToSign.Headers.Protected.SetAlgorithm(cose.AlgorithmES512)
 
 // sign message
-_ = msg.Sign(rand.Reader, nil, signer)
+_ = msgToSign.Sign(rand.Reader, nil, signer)
 
 // marshal message
-data, _ := msg.MarshalCBOR()
+data, _ := msgToSign.MarshalCBOR()
 ```
 
 Verify a raw COSE_Sign1 message. For example:
@@ -90,6 +90,21 @@ The supported algorithms can be extended at runtime by using [cose.RegisterAlgor
 
 [API docs](https://pkg.go.dev/github.com/veraison/go-cose)
 
+### Integer Ranges
+
+CBOR supports integers in the range:
+
+```text
+[-2<sup>64</sup>, -1] ∪ [0, 2<sup>64</sup> - 1]
+```
+
+This does not map onto a single Go integer type.
+
+`go-cose` uses `int64` to encompass both positive and negative values to keep data sizes smaller and easy to use.
+
+The main effect is that integer label values in the [-2<sup>64</sup>, -2<sup>63</sup> - 1] and the [2<sup>63</sup>, 2<sup>64</sup> - 1] ranges, which are nominally valid
+per RFC 8152, are rejected by the go-cose library.
+
 ### Conformance Tests
 
 go-cose runs the [GlueCOSE](https://github.com/gluecose/test-vectors) test suite on every local `go test` execution.

algorithm.go

@@ -56,13 +56,13 @@ type extAlgorithm struct {
 	Name string
 
 	// Hash is the hash algorithm associated with the algorithm.
-	// If HashFunc presents, Hash is ignored.
-	// If HashFunc does not present and Hash is set to 0, no hash is used.
+	// If HashFunc is present, Hash is ignored.
+	// If HashFunc is not present and Hash is set to 0, no hash is used.
 	Hash crypto.Hash
 
 	// HashFunc is the hash algorithm associated with the algorithm.
 	// HashFunc is preferred in the case that the hash algorithm is not
-	// supported by the golang build-in crypto hashes.
+	// supported by the golang built-in crypto hashes.
 	// For regular scenarios, use Hash instead.
 	HashFunc func() hash.Hash
 }
@@ -137,7 +137,7 @@ func (a Algorithm) newHash() (hash.Hash, error) {
 	return nil, ErrUnavailableHashFunc
 }
 
-// computeHash computing the digest using the hash specified in the algorithm.
+// computeHash computes the digest using the hash specified in the algorithm.
 // Returns the input data if no hash is required for the message.
 func (a Algorithm) computeHash(data []byte) ([]byte, error) {
 	h, err := a.newHash()
@@ -153,14 +153,14 @@ func (a Algorithm) computeHash(data []byte) ([]byte, error) {
 	return h.Sum(nil), nil
 }
 
-// RegisterAlgorithm provides extensibility for the cose library to support
+// RegisterAlgorithm provides extensibility for the COSE library to support
 // private algorithms or algorithms not yet registered in IANA.
 // The existing algorithms cannot be re-registered.
 // The parameter `hash` is the hash algorithm associated with the algorithm. If
-// hashFunc presents, hash is ignored. If hashFunc does not present and hash is
+// hashFunc is present, hash is ignored. If hashFunc is not present and hash is
 // set to 0, no hash is used for this algorithm.
 // The parameter `hashFunc` is preferred in the case that the hash algorithm is not
-// supported by the golang build-in crypto hashes.
+// supported by the golang built-in crypto hashes.
 func RegisterAlgorithm(alg Algorithm, name string, hash crypto.Hash, hashFunc func() hash.Hash) error {
 	if _, ok := alg.hashFunc(); ok {
 		return ErrAlgorithmRegistered

ecdsa.go

@@ -36,7 +36,7 @@ func OS2IP(x []byte) *big.Int {
 	return new(big.Int).SetBytes(x)
 }
 
-// ecdsaKeySigner is a ECDSA based signer with golang built-in keys.
+// ecdsaKeySigner is a ECDSA-based signer with golang built-in keys.
 type ecdsaKeySigner struct {
 	alg Algorithm
 	key *ecdsa.PrivateKey
@@ -47,8 +47,9 @@ func (es *ecdsaKeySigner) Algorithm() Algorithm {
 	return es.alg
 }
 
-// Sign signs digest with the private key, possibly using entropy from rand.
-// The resulting signature should follow RFC 8152 section 8.1.
+// Sign signs digest with the private key using entropy from rand.
+// The resulting signature should follow RFC 8152 section 8.1,
+// although it does not follow the recommendation of being deterministic.
 //
 // Reference: https://datatracker.ietf.org/doc/html/rfc8152#section-8.1
 func (es *ecdsaKeySigner) Sign(rand io.Reader, digest []byte) ([]byte, error) {
@@ -95,6 +96,8 @@ func (es *ecdsaCryptoSigner) Sign(rand io.Reader, digest []byte) ([]byte, error)
 
 // encodeECDSASignature encodes (r, s) into a signature binary string using the
 // method specified by RFC 8152 section 8.1.
+//
+// Reference: https://datatracker.ietf.org/doc/html/rfc8152#section-8.1
 func encodeECDSASignature(curve elliptic.Curve, r, s *big.Int) ([]byte, error) {
 	n := (curve.Params().BitSize + 7) / 8
 	sig := make([]byte, n*2)
@@ -109,6 +112,8 @@ func encodeECDSASignature(curve elliptic.Curve, r, s *big.Int) ([]byte, error) {
 
 // decodeECDSASignature decodes (r, s) from a signature binary string using the
 // method specified by RFC 8152 section 8.1.
+//
+// Reference: https://datatracker.ietf.org/doc/html/rfc8152#section-8.1
 func decodeECDSASignature(curve elliptic.Curve, sig []byte) (r, s *big.Int, err error) {
 	n := (curve.Params().BitSize + 7) / 8
 	if len(sig) != n*2 {

ed25519.go

@@ -6,7 +6,7 @@ import (
 	"io"
 )
 
-// ed25519Signer is a Pure EdDsA based signer with a generic crypto.Signer.
+// ed25519Signer is a Pure EdDSA based signer with a generic crypto.Signer.
 type ed25519Signer struct {
 	key crypto.Signer
 }
@@ -26,7 +26,7 @@ func (es *ed25519Signer) Sign(rand io.Reader, digest []byte) ([]byte, error) {
 	return es.key.Sign(rand, digest, crypto.Hash(0))
 }
 
-// ed25519Verifier is a Pure EdDsA based verifier with golang built-in keys.
+// ed25519Verifier is a Pure EdDSA based verifier with golang built-in keys.
 type ed25519Verifier struct {
 	key ed25519.PublicKey
 }

headers.go

@@ -143,7 +143,7 @@ func (h ProtectedHeader) Critical() ([]interface{}, error) {
 	return criticalLabels, nil
 }
 
-// ensureCritical ensures all critical headers present in the protected bucket.
+// ensureCritical ensures all critical headers are present in the protected bucket.
 func (h ProtectedHeader) ensureCritical() error {
 	labels, err := h.Critical()
 	if err != nil {

sign1.go

@@ -128,7 +128,7 @@ func (m *Sign1Message) Sign(rand io.Reader, external []byte, signer Signer) erro
 	}
 
 	// check algorithm if present.
-	// `alg` header MUST present if there is no externally supplied data.
+	// `alg` header MUST be present if there is no externally supplied data.
 	alg := signer.Algorithm()
 	err := m.Headers.ensureSigningAlgorithm(alg, external)
 	if err != nil {

signer.go

@@ -29,7 +29,7 @@ type Signer interface {
 // Developers are encouraged to implement the `cose.Signer` interface instead of
 // the `crypto.Signer` interface for better performance.
 //
-// All signing keys implementing `crypto.Signer`` with `Public()` outputing a
+// All signing keys implementing `crypto.Signer` with `Public()` returning a
 // public key of type `*rsa.PublicKey`, `*ecdsa.PublicKey`, or
 // `ed25519.PublicKey` are accepted.
 //
@@ -42,7 +42,7 @@ func NewSigner(alg Algorithm, key crypto.Signer) (Signer, error) {
 		if !ok {
 			return nil, fmt.Errorf("%v: %w", alg, ErrAlgorithmMismatch)
 		}
-		// RFC 8230 6.1 requires RSA keys having a minimun size of 2048 bits.
+		// RFC 8230 6.1 requires RSA keys having a minimum size of 2048 bits.
 		// Reference: https://www.rfc-editor.org/rfc/rfc8230.html#section-6.1
 		if vk.N.BitLen() < 2048 {
 			return nil, errors.New("RSA key must be at least 2048 bits long")