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

Author: Dillon Streator

hmac.go

@@ -46,6 +46,14 @@ func (m *SigningMethodHMAC) Alg() string {
 }
 
 // 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.
+// i.e. crypto/rand https://pkg.go.dev/crypto/rand#Read
+//
+// Storing keys in the environment can be done by base64 encoding the cryptographically random []byte.
+// Reading keys from the environment can be done by base64 decoding the environment variable to retrieve the original cryptographically random []byte.
+// i.e. encoding/base64 https://pkg.go.dev/encoding/base64#Encoding.DecodeString
 func (m *SigningMethodHMAC) Verify(signingString, signature string, key interface{}) error {
 	// Verify the key is the right type
 	keyBytes, ok := key.([]byte)
@@ -79,6 +87,13 @@ func (m *SigningMethodHMAC) Verify(signingString, signature string, key interfac
 
 // 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.
+// i.e. crypto/rand https://pkg.go.dev/crypto/rand#Read
+//
+// Storing keys in your environment can be done by base64 encoding the cryptographically random []byte.
+// Reading keys from the environment can be done by base64 decoding the environment variable to retrieve the original cryptographically random []byte.
+// i.e. encoding/base64 https://pkg.go.dev/encoding/base64#Encoding.DecodeString
 func (m *SigningMethodHMAC) Sign(signingString string, key interface{}) (string, error) {
 	if keyBytes, ok := key.([]byte); ok {
 		if !m.Hash.Available() {

token.go

@@ -55,6 +55,17 @@ func NewWithClaims(method SigningMethod, claims Claims) *Token {
 
 // SignedString creates and returns a complete, signed JWT.
 // The token is signed using the SigningMethod specified in the token.
+// Note it is not advised to provide a []byte which was converted from a 'human readable' string using a subset of ASCII characters.
+// i.e.
+// token.SignedString([]byte(os.Getenv("JWT_SECRET")))
+// where `JWT_SECRET“ is some random string containing the subset of ASCII characters which is synonymous with string based keys
+//
+// To maximize entropy, you should ideally be providing a []byte key which was produced from a cryptographically random source.
+// i.e. crypto/rand https://pkg.go.dev/crypto/rand#Read
+//
+// Storing keys in the environment can be done by base64 encoding the cryptographically random []byte.
+// Reading keys from the environment can be done by base64 decoding the environment variable to retrieve the original cryptographically random []byte.
+// i.e. encoding/base64 https://pkg.go.dev/encoding/base64#Encoding.DecodeString
 func (t *Token) SignedString(key interface{}) (string, error) {
 	var sig, sstr string
 	var err error