New validation API

claims.go

@@ -1,177 +1,16 @@
 package jwt
 
-import (
-	"crypto/subtle"
-	"fmt"
-	"time"
-)
-
-// Claims must just have a Valid method that determines
-// if the token is invalid for any supported reason
+// Claims represent any form of a JWT Claims Set according to
+// https://datatracker.ietf.org/doc/html/rfc7519#section-4. In order to have a
+// common basis for validation, it is required that an implementation is able to
+// supply at least the claim names provided in
+// https://datatracker.ietf.org/doc/html/rfc7519#section-4.1 namely `exp`,
+// `iat`, `nbf`, `iss` and `aud`.
 type Claims interface {
-	Valid() error
-}
-
-// RegisteredClaims are a structured version of the JWT Claims Set,
-// restricted to Registered Claim Names, as referenced at
-// https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
-//
-// This type can be used on its own, but then additional private and
-// public claims embedded in the JWT will not be parsed. The typical usecase
-// therefore is to embedded this in a user-defined claim type.
-//
-// See examples for how to use this with your own claim types.
-type RegisteredClaims struct {
-	// the `iss` (Issuer) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1
-	Issuer string `json:"iss,omitempty"`
-
-	// the `sub` (Subject) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2
-	Subject string `json:"sub,omitempty"`
-
-	// the `aud` (Audience) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3
-	Audience ClaimStrings `json:"aud,omitempty"`
-
-	// the `exp` (Expiration Time) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4
-	ExpiresAt *NumericDate `json:"exp,omitempty"`
-
-	// the `nbf` (Not Before) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5
-	NotBefore *NumericDate `json:"nbf,omitempty"`
-
-	// the `iat` (Issued At) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6
-	IssuedAt *NumericDate `json:"iat,omitempty"`
-
-	// the `jti` (JWT ID) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7
-	ID string `json:"jti,omitempty"`
-}
-
-// Valid validates time based claims "exp, iat, nbf".
-// There is no accounting for clock skew.
-// As well, if any of the above claims are not in the token, it will still
-// be considered a valid claim.
-func (c RegisteredClaims) Valid() error {
-	vErr := new(ValidationError)
-	now := TimeFunc()
-
-	// The claims below are optional, by default, so if they are set to the
-	// default value in Go, let's not fail the verification for them.
-	if !c.VerifyExpiresAt(now, false) {
-		delta := now.Sub(c.ExpiresAt.Time)
-		vErr.Inner = fmt.Errorf("%s by %s", ErrTokenExpired, delta)
-		vErr.Errors |= ValidationErrorExpired
-	}
-
-	if !c.VerifyIssuedAt(now, false) {
-		vErr.Inner = ErrTokenUsedBeforeIssued
-		vErr.Errors |= ValidationErrorIssuedAt
-	}
-
-	if !c.VerifyNotBefore(now, false) {
-		vErr.Inner = ErrTokenNotValidYet
-		vErr.Errors |= ValidationErrorNotValidYet
-	}
-
-	if vErr.valid() {
-		return nil
-	}
-
-	return vErr
-}
-
-// VerifyAudience compares the aud claim against cmp.
-// If required is false, this method will return true if the value matches or is unset
-func (c *RegisteredClaims) VerifyAudience(cmp string, req bool) bool {
-	return verifyAud(c.Audience, cmp, req)
-}
-
-// VerifyExpiresAt compares the exp claim against cmp (cmp < exp).
-// If req is false, it will return true, if exp is unset.
-func (c *RegisteredClaims) VerifyExpiresAt(cmp time.Time, req bool) bool {
-	if c.ExpiresAt == nil {
-		return verifyExp(nil, cmp, req)
-	}
-
-	return verifyExp(&c.ExpiresAt.Time, cmp, req)
-}
-
-// VerifyIssuedAt compares the iat claim against cmp (cmp >= iat).
-// If req is false, it will return true, if iat is unset.
-func (c *RegisteredClaims) VerifyIssuedAt(cmp time.Time, req bool) bool {
-	if c.IssuedAt == nil {
-		return verifyIat(nil, cmp, req)
-	}
-
-	return verifyIat(&c.IssuedAt.Time, cmp, req)
-}
-
-// VerifyNotBefore compares the nbf claim against cmp (cmp >= nbf).
-// If req is false, it will return true, if nbf is unset.
-func (c *RegisteredClaims) VerifyNotBefore(cmp time.Time, req bool) bool {
-	if c.NotBefore == nil {
-		return verifyNbf(nil, cmp, req)
-	}
-
-	return verifyNbf(&c.NotBefore.Time, cmp, req)
-}
-
-// VerifyIssuer compares the iss claim against cmp.
-// If required is false, this method will return true if the value matches or is unset
-func (c *RegisteredClaims) VerifyIssuer(cmp string, req bool) bool {
-	return verifyIss(c.Issuer, cmp, req)
-}
-
-// ----- helpers
-
-func verifyAud(aud []string, cmp string, required bool) bool {
-	if len(aud) == 0 {
-		return !required
-	}
-	// use a var here to keep constant time compare when looping over a number of claims
-	result := false
-
-	var stringClaims string
-	for _, a := range aud {
-		if subtle.ConstantTimeCompare([]byte(a), []byte(cmp)) != 0 {
-			result = true
-		}
-		stringClaims = stringClaims + a
-	}
-
-	// case where "" is sent in one or many aud claims
-	if len(stringClaims) == 0 {
-		return !required
-	}
-
-	return result
-}
-
-func verifyExp(exp *time.Time, now time.Time, required bool) bool {
-	if exp == nil {
-		return !required
-	}
-	return now.Before(*exp)
-}
-
-func verifyIat(iat *time.Time, now time.Time, required bool) bool {
-	if iat == nil {
-		return !required
-	}
-	return now.After(*iat) || now.Equal(*iat)
-}
-
-func verifyNbf(nbf *time.Time, now time.Time, required bool) bool {
-	if nbf == nil {
-		return !required
-	}
-	return now.After(*nbf) || now.Equal(*nbf)
-}
-
-func verifyIss(iss string, cmp string, required bool) bool {
-	if iss == "" {
-		return !required
-	}
-	if subtle.ConstantTimeCompare([]byte(iss), []byte(cmp)) != 0 {
-		return true
-	} else {
-		return false
-	}
+	GetExpirationTime() (*NumericDate, error)
+	GetIssuedAt() (*NumericDate, error)
+	GetNotBefore() (*NumericDate, error)
+	GetIssuer() (string, error)
+	GetSubject() (string, error)
+	GetAudience() (ClaimStrings, error)
 }

errors.go

@@ -18,6 +18,7 @@ var (
 	ErrTokenExpired          = errors.New("token is expired")
 	ErrTokenUsedBeforeIssued = errors.New("token used before issued")
 	ErrTokenInvalidIssuer    = errors.New("token has invalid issuer")
+	ErrTokenInvalidSubject   = errors.New("token has invalid subject")
 	ErrTokenNotValidYet      = errors.New("token is not valid yet")
 	ErrTokenInvalidId        = errors.New("token has invalid id")
 	ErrTokenInvalidClaims    = errors.New("token has invalid claims")
@@ -29,11 +30,12 @@ const (
 	ValidationErrorUnverifiable                        // Token could not be verified because of signing problems
 	ValidationErrorSignatureInvalid                    // Signature validation failed
 
-	// Standard Claim validation errors
+	// Registered Claim validation errors
 	ValidationErrorAudience      // AUD validation failed
 	ValidationErrorExpired       // EXP validation failed
 	ValidationErrorIssuedAt      // IAT validation failed
 	ValidationErrorIssuer        // ISS validation failed
+	ValidationErrorSubject       // SUB validation failed
 	ValidationErrorNotValidYet   // NBF validation failed
 	ValidationErrorId            // JTI validation failed
 	ValidationErrorClaimsInvalid // Generic claims validation error

example_test.go

@@ -70,7 +70,7 @@ func ExampleNewWithClaims_customClaimsType() {
 	//Output: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIiLCJpc3MiOiJ0ZXN0IiwiZXhwIjoxNTE2MjM5MDIyfQ.xVuY2FZ_MRXMIEgVQ7J-TFtaucVFRXUzHm9LmV41goM <nil>
 }
 
-// Example creating a token using a custom claims type.  The StandardClaim is embedded
+// Example creating a token using a custom claims type.  The RegisteredClaims is embedded
 // in the custom type to allow for easy encoding, parsing and validation of standard claims.
 func ExampleParseWithClaims_customClaimsType() {
 	tokenString := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIiLCJpc3MiOiJ0ZXN0IiwiYXVkIjoic2luZ2xlIn0.QAWg1vGvnqRuCFTMcPkjZljXHh8U3L_qUjszOtQbeaA"
@@ -93,7 +93,63 @@ func ExampleParseWithClaims_customClaimsType() {
 	// Output: bar test
 }
 
-// An example of parsing the error types using bitfield checks
+// Example creating a token using a custom claims type and validation options.  The RegisteredClaims is embedded
+// in the custom type to allow for easy encoding, parsing and validation of standard claims.
+func ExampleParseWithClaims_validationOptions() {
+	tokenString := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIiLCJpc3MiOiJ0ZXN0IiwiYXVkIjoic2luZ2xlIn0.QAWg1vGvnqRuCFTMcPkjZljXHh8U3L_qUjszOtQbeaA"
+
+	type MyCustomClaims struct {
+		Foo string `json:"foo"`
+		jwt.RegisteredClaims
+	}
+
+	token, err := jwt.ParseWithClaims(tokenString, &MyCustomClaims{}, func(token *jwt.Token) (interface{}, error) {
+		return []byte("AllYourBase"), nil
+	}, jwt.WithLeeway(5*time.Second))
+
+	if claims, ok := token.Claims.(*MyCustomClaims); ok && token.Valid {
+		fmt.Printf("%v %v", claims.Foo, claims.RegisteredClaims.Issuer)
+	} else {
+		fmt.Println(err)
+	}
+
+	// Output: bar test
+}
+
+type MyCustomClaims struct {
+	Foo string `json:"foo"`
+	jwt.RegisteredClaims
+}
+
+func (m MyCustomClaims) CustomValidation() error {
+	if m.Foo != "bar" {
+		return errors.New("must be foobar")
+	}
+
+	return nil
+}
+
+// Example creating a token using a custom claims type and validation options.
+// The RegisteredClaims is embedded in the custom type to allow for easy
+// encoding, parsing and validation of standard claims and the function
+// CustomValidation is implemented.
+func ExampleParseWithClaims_customValidation() {
+	tokenString := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIiLCJpc3MiOiJ0ZXN0IiwiYXVkIjoic2luZ2xlIn0.QAWg1vGvnqRuCFTMcPkjZljXHh8U3L_qUjszOtQbeaA"
+
+	token, err := jwt.ParseWithClaims(tokenString, &MyCustomClaims{}, func(token *jwt.Token) (interface{}, error) {
+		return []byte("AllYourBase"), nil
+	}, jwt.WithLeeway(5*time.Second))
+
+	if claims, ok := token.Claims.(*MyCustomClaims); ok && token.Valid {
+		fmt.Printf("%v %v", claims.Foo, claims.RegisteredClaims.Issuer)
+	} else {
+		fmt.Println(err)
+	}
+
+	// Output: bar test
+}
+
+// An example of parsing the error types using errors.Is.
 func ExampleParse_errorChecking() {
 	// Token from another example.  This token is expired
 	var tokenString = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIiLCJleHAiOjE1MDAwLCJpc3MiOiJ0ZXN0In0.HE7fK0xOQwFEr4WDgRWj4teRPZ6i3GLwD5YCm6Pwu_c"