From e6b469960bb15e0435f0cc550c6a24f880decdec Mon Sep 17 00:00:00 2001 From: qmuntal Date: Tue, 3 May 2022 18:08:31 +0200 Subject: [PATCH] documentation cleanup Signed-off-by: qmuntal --- README.md | 23 +++++++++++++++++++---- algorithm.go | 14 +++++++------- ecdsa.go | 11 ++++++++--- ed25519.go | 4 ++-- headers.go | 2 +- sign1.go | 2 +- signer.go | 4 ++-- 7 files changed, 40 insertions(+), 20 deletions(-) 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")