v5 Pre-Release

MIGRATION_GUIDE.md

@@ -2,18 +2,18 @@
 
 Starting from [v4.0.0](https://github.com/golang-jwt/jwt/releases/tag/v4.0.0), the import path will be:
 
-    "github.com/golang-jwt/jwt/v4"
+    "github.com/golang-jwt/jwt/v5"
 
 The `/v4` version will be backwards compatible with existing `v3.x.y` tags in this repo, as well as 
 `github.com/dgrijalva/jwt-go`. For most users this should be a drop-in replacement, if you're having 
 troubles migrating, please open an issue.
 
-You can replace all occurrences of `github.com/dgrijalva/jwt-go` or `github.com/golang-jwt/jwt` with `github.com/golang-jwt/jwt/v4`, either manually or by using tools such as `sed` or `gofmt`.
+You can replace all occurrences of `github.com/dgrijalva/jwt-go` or `github.com/golang-jwt/jwt` with `github.com/golang-jwt/jwt/v5`, either manually or by using tools such as `sed` or `gofmt`.
 
 And then you'd typically run:
 
 ```
-go get github.com/golang-jwt/jwt/v4
+go get github.com/golang-jwt/jwt/v5
 go mod tidy
 ```
 

README.md

@@ -1,12 +1,12 @@
 # jwt-go
 
 [![build](https://github.com/golang-jwt/jwt/actions/workflows/build.yml/badge.svg)](https://github.com/golang-jwt/jwt/actions/workflows/build.yml)
-[![Go Reference](https://pkg.go.dev/badge/github.com/golang-jwt/jwt/v4.svg)](https://pkg.go.dev/github.com/golang-jwt/jwt/v4)
+[![Go Reference](https://pkg.go.dev/badge/github.com/golang-jwt/jwt/v5.svg)](https://pkg.go.dev/github.com/golang-jwt/jwt/v5)
 
 A [go](http://www.golang.org) (or 'golang' for search engine friendliness) implementation of [JSON Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519).
 
 Starting with [v4.0.0](https://github.com/golang-jwt/jwt/releases/tag/v4.0.0) this project adds Go module support, but maintains backwards compatibility with older `v3.x.y` tags and upstream `github.com/dgrijalva/jwt-go`.
-See the [`MIGRATION_GUIDE.md`](./MIGRATION_GUIDE.md) for more information.
+See the [`MIGRATION_GUIDE.md`](./MIGRATION_GUIDE.md) for more information. Version v5.0.0 introduces major improvements to the validation of tokens, but is not entirely backwards compatible. 
 
 > After the original author of the library suggested migrating the maintenance of `jwt-go`, a dedicated team of open source maintainers decided to clone the existing library into this repository. See [dgrijalva/jwt-go#462](https://github.com/dgrijalva/jwt-go/issues/462) for a detailed discussion on this topic.
 
@@ -41,22 +41,22 @@ This library supports the parsing and verification as well as the generation and
 1. To install the jwt package, you first need to have [Go](https://go.dev/doc/install) installed, then you can use the command below to add `jwt-go` as a dependency in your Go program.
 
 ```sh
-go get -u github.com/golang-jwt/jwt/v4
+go get -u github.com/golang-jwt/jwt/v5
 ```
 
 2. Import it in your code:
 
 ```go
-import "github.com/golang-jwt/jwt/v4"
+import "github.com/golang-jwt/jwt/v5"
 ```
 
 ## Examples
 
-See [the project documentation](https://pkg.go.dev/github.com/golang-jwt/jwt/v4) for examples of usage:
+See [the project documentation](https://pkg.go.dev/github.com/golang-jwt/jwt/v5) for examples of usage:
 
-* [Simple example of parsing and validating a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#example-Parse-Hmac)
-* [Simple example of building and signing a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#example-New-Hmac)
-* [Directory of Examples](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#pkg-examples)
+* [Simple example of parsing and validating a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#example-Parse-Hmac)
+* [Simple example of building and signing a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#example-New-Hmac)
+* [Directory of Examples](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#pkg-examples)
 
 ## Extensions
 
@@ -68,7 +68,7 @@ A common use case would be integrating with different 3rd party signature provid
 | --------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
 | GCP       | Integrates with multiple Google Cloud Platform signing tools (AppEngine, IAM API, Cloud KMS)             | https://github.com/someone1/gcp-jwt-go     |
 | AWS       | Integrates with AWS Key Management Service, KMS                                                          | https://github.com/matelang/jwt-go-aws-kms |
-| JWKS      | Provides support for JWKS ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) as a `jwt.Keyfunc` | https://github.com/MicahParks/keyfunc       |
+| JWKS      | Provides support for JWKS ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) as a `jwt.Keyfunc` | https://github.com/MicahParks/keyfunc      |
 
 *Disclaimer*: Unless otherwise specified, these integrations are maintained by third parties and should not be considered as a primary offer by any of the mentioned cloud providers
 
@@ -110,10 +110,10 @@ Asymmetric signing methods, such as RSA, use different keys for signing and veri
 
 Each signing method expects a different object type for its signing keys. See the package documentation for details. Here are the most common ones:
 
-* The [HMAC signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodHMAC) (`HS256`,`HS384`,`HS512`) expect `[]byte` values for signing and validation
-* The [RSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodRSA) (`RS256`,`RS384`,`RS512`) expect `*rsa.PrivateKey` for signing and `*rsa.PublicKey` for validation
-* The [ECDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodECDSA) (`ES256`,`ES384`,`ES512`) expect `*ecdsa.PrivateKey` for signing and `*ecdsa.PublicKey` for validation
-* The [EdDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodEd25519) (`Ed25519`) expect `ed25519.PrivateKey` for signing and `ed25519.PublicKey` for validation
+* The [HMAC signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodHMAC) (`HS256`,`HS384`,`HS512`) expect `[]byte` values for signing and validation
+* The [RSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodRSA) (`RS256`,`RS384`,`RS512`) expect `*rsa.PrivateKey` for signing and `*rsa.PublicKey` for validation
+* The [ECDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodECDSA) (`ES256`,`ES384`,`ES512`) expect `*ecdsa.PrivateKey` for signing and `*ecdsa.PublicKey` for validation
+* The [EdDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodEd25519) (`Ed25519`) expect `ed25519.PrivateKey` for signing and `ed25519.PublicKey` for validation
 
 ### JWT and OAuth
 
@@ -131,7 +131,7 @@ This library uses descriptive error messages whenever possible. If you are not g
 
 ## More
 
-Documentation can be found [on pkg.go.dev](https://pkg.go.dev/github.com/golang-jwt/jwt/v4).
+Documentation can be found [on pkg.go.dev](https://pkg.go.dev/github.com/golang-jwt/jwt/v5).
 
 The command line utility included in this project (cmd/jwt) provides a straightforward example of token creation and parsing as well as a useful tool for debugging your own integration. You'll also find several implementation examples in the documentation.
 

claims.go

@@ -1,269 +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)
-}
-
-// StandardClaims are a structured version of the JWT Claims Set, as referenced at
-// https://datatracker.ietf.org/doc/html/rfc7519#section-4. They do not follow the
-// specification exactly, since they were based on an earlier draft of the
-// specification and not updated. The main difference is that they only
-// support integer-based date fields and singular audiences. This might lead to
-// incompatibilities with other JWT implementations. The use of this is discouraged, instead
-// the newer RegisteredClaims struct should be used.
-//
-// Deprecated: Use RegisteredClaims instead for a forward-compatible way to access registered claims in a struct.
-type StandardClaims struct {
-	Audience  string `json:"aud,omitempty"`
-	ExpiresAt int64  `json:"exp,omitempty"`
-	Id        string `json:"jti,omitempty"`
-	IssuedAt  int64  `json:"iat,omitempty"`
-	Issuer    string `json:"iss,omitempty"`
-	NotBefore int64  `json:"nbf,omitempty"`
-	Subject   string `json:"sub,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 StandardClaims) Valid() error {
-	vErr := new(ValidationError)
-	now := TimeFunc().Unix()
-
-	// 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 := time.Unix(now, 0).Sub(time.Unix(c.ExpiresAt, 0))
-		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 *StandardClaims) VerifyAudience(cmp string, req bool) bool {
-	return verifyAud([]string{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 *StandardClaims) VerifyExpiresAt(cmp int64, req bool) bool {
-	if c.ExpiresAt == 0 {
-		return verifyExp(nil, time.Unix(cmp, 0), req)
-	}
-
-	t := time.Unix(c.ExpiresAt, 0)
-	return verifyExp(&t, time.Unix(cmp, 0), req)
-}
-
-// VerifyIssuedAt compares the iat claim against cmp (cmp >= iat).
-// If req is false, it will return true, if iat is unset.
-func (c *StandardClaims) VerifyIssuedAt(cmp int64, req bool) bool {
-	if c.IssuedAt == 0 {
-		return verifyIat(nil, time.Unix(cmp, 0), req)
-	}
-
-	t := time.Unix(c.IssuedAt, 0)
-	return verifyIat(&t, time.Unix(cmp, 0), req)
-}
-
-// VerifyNotBefore compares the nbf claim against cmp (cmp >= nbf).
-// If req is false, it will return true, if nbf is unset.
-func (c *StandardClaims) VerifyNotBefore(cmp int64, req bool) bool {
-	if c.NotBefore == 0 {
-		return verifyNbf(nil, time.Unix(cmp, 0), req)
-	}
-
-	t := time.Unix(c.NotBefore, 0)
-	return verifyNbf(&t, time.Unix(cmp, 0), 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 *StandardClaims) 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
-	}
-	return subtle.ConstantTimeCompare([]byte(iss), []byte(cmp)) != 0
+	GetExpirationTime() (*NumericDate, error)
+	GetIssuedAt() (*NumericDate, error)
+	GetNotBefore() (*NumericDate, error)
+	GetIssuer() (string, error)
+	GetSubject() (string, error)
+	GetAudience() (ClaimStrings, error)
 }

cmd/jwt/README.md

@@ -16,4 +16,4 @@ To simply display a token, use:
 
 You can install this tool with the following command:
 
-     go install github.com/golang-jwt/jwt/v4/cmd/jwt
+     go install github.com/golang-jwt/jwt/v5/cmd/jwt

cmd/jwt/main.go

@@ -17,7 +17,7 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/golang-jwt/jwt/v4"
+	"github.com/golang-jwt/jwt/v5"
 )
 
 var (