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 <dillonstreator@Dillons-2nd-MacBook-Pro.local>
Co-authored-by: Christian Banse <oxisto@aybaze.com>
This commit is contained in:
dillonstreator 2023-03-31 06:19:48 -05:00 committed by GitHub
parent 1c4047f488
commit 843e9bfe4d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 22 additions and 4 deletions

21
hmac.go
View File

@ -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() {

View File

@ -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 {