From c0ffb890f3ef872362d810ebc17730c47b9c33ca Mon Sep 17 00:00:00 2001
From: Sebastien Rosset <serosset@cisco.com>
Date: Fri, 15 Oct 2021 05:48:31 -0700
Subject: [PATCH] Improve code comments, including security consideration
 (#107)

* improve code comments, including security consideration

* Add link to URL with details about security vulnerabilities.

* Update token.go

Co-authored-by: Christian Banse <oxisto@aybaze.com>

* Update token.go

Co-authored-by: Christian Banse <oxisto@aybaze.com>

* update code comments

Co-authored-by: Christian Banse <oxisto@aybaze.com>
---
 parser.go |  3 +--
 token.go  | 16 +++++++++++-----
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/parser.go b/parser.go
index af2dfd33..2f61a69d 100644
--- a/parser.go
+++ b/parser.go
@@ -36,9 +36,8 @@ func NewParser(options ...ParserOption) *Parser {
 	return p
 }
 
-// Parse parses, validates, and returns a token.
+// Parse parses, validates, verifies the signature and returns the parsed token.
 // keyFunc will receive the parsed token and should return the key for validating.
-// If everything is kosher, err will be nil
 func (p *Parser) Parse(tokenString string, keyFunc Keyfunc) (*Token, error) {
 	return p.ParseWithClaims(tokenString, MapClaims{}, keyFunc)
 }
diff --git a/token.go b/token.go
index e4d090b0..4c93e7aa 100644
--- a/token.go
+++ b/token.go
@@ -29,11 +29,12 @@ type Token struct {
 	Valid     bool                   // Is the token valid?  Populated when you Parse/Verify a token
 }
 
-// New creates a new Token.  Takes a signing method
+// New creates a new Token with the specified signing method and an empty map of claims.
 func New(method SigningMethod) *Token {
 	return NewWithClaims(method, MapClaims{})
 }
 
+// NewWithClaims creates a new Token with the specified signing method and claims.
 func NewWithClaims(method SigningMethod, claims Claims) *Token {
 	return &Token{
 		Header: map[string]interface{}{
@@ -45,7 +46,8 @@ func NewWithClaims(method SigningMethod, claims Claims) *Token {
 	}
 }
 
-// SignedString retrieves the complete, signed token
+// SignedString creates and returns a complete, signed JWT.
+// The token is signed using the SigningMethod specified in the token.
 func (t *Token) SignedString(key interface{}) (string, error) {
 	var sig, sstr string
 	var err error
@@ -82,9 +84,13 @@ func (t *Token) SigningString() (string, error) {
 	return strings.Join(parts, "."), nil
 }
 
-// Parse parses, validates, and returns a token.
-// keyFunc will receive the parsed token and should return the key for validating.
-// If everything is kosher, err will be nil
+// Parse parses, validates, verifies the signature and returns the parsed token.
+// keyFunc will receive the parsed token and should return the cryptographic key
+// for verifying the signature.
+// The caller is strongly encouraged to set the WithValidMethods option to
+// validate the 'alg' claim in the token matches the expected algorithm.
+// For more details about the importance of validating the 'alg' claim,
+// see https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
 func Parse(tokenString string, keyFunc Keyfunc, options ...ParserOption) (*Token, error) {
 	return NewParser(options...).Parse(tokenString, keyFunc)
 }