add documentation to hmac Verify & Sign to detail why string is not an advisable input for key (#249)

* add documentation around Verify & Sign to detail why string is not an advisable input for key

* Refer to the usage guide

---------

Co-authored-by: Dillon Streator <[email protected]>
Co-authored-by: Christian Banse <[email protected]>

Author: 3 people

hmac.go

@@ -45,7 +45,16 @@ func (m *SigningMethodHMAC) Alg() string {
 	return m.Name
 }
 
-// Verify implements token verification for the SigningMethod. Returns nil if the signature is valid.
+// Verify implements token verification for the SigningMethod. Returns nil if
+// the signature is valid. Key must be []byte.
+//
+// Note it is not advised to provide a []byte which was converted from a 'human
+// readable' string using a subset of ASCII characters. To maximize entropy, you
+// should ideally be providing a []byte key which was produced from a
+// cryptographically random source, e.g. crypto/rand. Additional information
+// about this, and why we intentionally are not supporting string as a key can
+// be found on our usage guide
+// https://golang-jwt.github.io/jwt/usage/signing_methods/#signing-methods-and-key-types.
 func (m *SigningMethodHMAC) Verify(signingString string, sig []byte, key interface{}) error {
 	// Verify the key is the right type
 	keyBytes, ok := key.([]byte)
@@ -71,8 +80,14 @@ func (m *SigningMethodHMAC) Verify(signingString string, sig []byte, key interfa
 	return nil
 }
 
-// Sign implements token signing for the SigningMethod.
-// Key must be []byte
+// Sign implements token signing for the SigningMethod. Key must be []byte.
+//
+// Note it is not advised to provide a []byte which was converted from a 'human
+// readable' string using a subset of ASCII characters. To maximize entropy, you
+// should ideally be providing a []byte key which was produced from a
+// cryptographically random source, e.g. crypto/rand. Additional information
+// about this, and why we intentionally are not supporting string as a key can
+// be found on our usage guide https://golang-jwt.github.io/jwt/usage/signing_methods/.
 func (m *SigningMethodHMAC) Sign(signingString string, key interface{}) ([]byte, error) {
 	if keyBytes, ok := key.([]byte); ok {
 		if !m.Hash.Available() {

token.go

@@ -42,7 +42,10 @@ func NewWithClaims(method SigningMethod, claims Claims, opts ...TokenOption) *To
 }
 
 // SignedString creates and returns a complete, signed JWT. The token is signed
-// using the SigningMethod specified in the token.
+// using the SigningMethod specified in the token. Please refer to
+// https://golang-jwt.github.io/jwt/usage/signing_methods/#signing-methods-and-key-types
+// for an overview of the different signing methods and their respective key
+// types.
 func (t *Token) SignedString(key interface{}) (string, error) {
 	sstr, err := t.SigningString()
 	if err != nil {