Tweak 994 (#995)

* Move location where AsymmetricKey is defined

* Tweak docs

* Update Changes

Changes

@@ -4,6 +4,19 @@ Changes
 v2 has many incompatibilities with v1. To see the full list of differences between
 v1 and v2, please read the Changes-v2.md file (https://github.com/lestrrat-go/jwx/blob/develop/v2/Changes-v2.md)
 
+v2.0.14 UNRELEASED
+  [New Features]
+  * [jwk] jwk.IsPrivateKey(), as well as jwk.AsymmetricKey has been added.
+    The function can be used to tell if a jwk.Key is a private key of an
+    asymmetric key pair.
+  [Security]
+  * golang.org/x/crypto has been updated to 0.14.0. The update contains a fix for HTTP/2
+    rapid reset DoS vulnerability, which some security scanning softwares may flag.
+    However, do note that this library is NOT affected by the issue, as it does not have
+    the capability to serve as an HTTP/2 server. This is included in this release
+    document so that users will be able to tell why this library may be flagged
+    when/if their scanning software do so.
+
 v2.0.13 26 Sep 2023
 [New Features]
   * [jwk] jwk.Equal has been added. Please note that this is equivalent to

jwk/interface.go

@@ -10,6 +10,13 @@ import (
 	"github.com/lestrrat-go/jwx/v2/internal/json"
 )
 
+// AsymmetricKey describes a Key that represents an key in an asymmetric key pair,
+// which in turn can be either a private or a public key. This interface
+// allows those keys to be queried if they are one or the other.
+type AsymmetricKey interface {
+	IsPrivate() bool
+}
+
 // KeyUsageType is used to denote what this key should be used for
 type KeyUsageType string
 

jwk/jwk.go

@@ -745,12 +745,15 @@ func Equal(k1, k2 Key) bool {
 	return bytes.Equal(tp1, tp2)
 }
 
-// IsPrivateKey tells whether the supplied key is a private or public key.  An
-// error is raised if the supplied key is not an AsymmetricKey.
+// IsPrivateKey returns true if the supplied key is a private key of an
+// asymmetric key pair. The argument `k` must implement the `AsymmetricKey`
+// interface.
+//
+// An error is returned if the supplied key is not an `AsymmetricKey`.
 func IsPrivateKey(k Key) (bool, error) {
 	asymmetric, ok := k.(AsymmetricKey)
 	if ok {
 		return asymmetric.IsPrivate(), nil
 	}
-	return false, fmt.Errorf("%T is not an asymmetric key", k)
+	return false, fmt.Errorf("jwk.IsPrivateKey: %T is not an asymmetric key", k)
 }

tools/cmd/genjwk/main.go

@@ -626,12 +626,6 @@ func generateGenericHeaders(fields codegen.FieldList) error {
 	}
 	o.L(")") // end const
 
-	o.LL("// AsymmetricKey is able to indicate if it's a public ")
-	o.L("// or private key.")
-	o.L("type AsymmetricKey interface {")
-	o.L("IsPrivate() bool")
-	o.L("}")
-
 	o.LL("// Key defines the minimal interface for each of the")
 	o.L("// key types. Their use and implementation differ significantly")
 	o.L("// between each key types, so you should use type assertions")