diff --git a/README.md b/README.md
index 7bdf415..fc26287 100644
--- a/README.md
+++ b/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
+[-264, -1] ∪ [0, 264 - 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 [-264, -263 - 1] and the [263, 264 - 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.
diff --git a/algorithm.go b/algorithm.go
index f7bd557..1ed8d38 100644
--- a/algorithm.go
+++ b/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
diff --git a/ecdsa.go b/ecdsa.go
index 33c796f..aa81a95 100644
--- a/ecdsa.go
+++ b/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 {
diff --git a/ed25519.go b/ed25519.go
index 30929f7..f87deee 100644
--- a/ed25519.go
+++ b/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
}
diff --git a/headers.go b/headers.go
index 8422b7e..2de06a8 100644
--- a/headers.go
+++ b/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 {
diff --git a/sign1.go b/sign1.go
index 51d6b3c..9d8606f 100644
--- a/sign1.go
+++ b/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 {
diff --git a/signer.go b/signer.go
index a0b5c5d..aa8d7d1 100644
--- a/signer.go
+++ b/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")