Skip to content

adjust documentation of Parse() #393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

adjust documentation of Parse() #393

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions parser.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,13 +215,13 @@ func (p *Parser) DecodeSegment(seg string) ([]byte, error) {
return encoding.DecodeString(seg)
}

// 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/
// Parse parses, validates, verifies the signature, and returns the parsed token.
// When a keyFunc is set and a tokenString is provided, the library will not accept
// the 'none' type algorithm, ensuring security by default. However, it is strongly
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not entirely correct. By default no token is rejected based on an algorithm value alone. The specified algorithms is matched against a list of available algorithms GetSigningMethod:

jwt/signing_method.go

Line 30 in 62e504c

func GetSigningMethod(alg string) (method SigningMethod) {

After this step, the key returned in keyFunc is forwarded to the signing method implementation, which checks whether the type of key is suitable for that particular method or not.

In order to avoid simple mistakes, the signing method of none only allows keys of a very special global variable jwt.UnsafeAllowNoneSignatureType.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I captured this, but just not that intricate detail. The main reason why I made the change here is that from the original comment it is not quite clear if the Parse function will be secure by default or not. It just mentions a rather unclear recommendation "caller is strongly encouraged to set the WithValidMethods option".

But hey, if you have a better idea for wording I'm all for it. I'm just looking to make the documentation clearer for users.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Understood. I will try to come up with a very condensed version of what I wrote for the doc. The issue that I have with the wording "When a keyFunc is set and a tokenString is provided, the library will not accept the 'none' type algorithm, ensuring security by default" is that strictly speaking is not true. If you have a keyFunc that returns jwt.UnsafeAllowNoneSignatureType it will accept the 'none' type. The 'none' type does not have any special handling.

// recommended to explicitly specify the allowed algorithms using the WithValidMethods
// option to ensure the 'none' type algorithm is definitively rejected. For more
// information on 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)
}
Expand Down