Key rotation with VerificationKeySet

parser.go

@@ -74,24 +74,40 @@ func (p *Parser) ParseWithClaims(tokenString string, claims Claims, keyFunc Keyf
 		}
 	}
 
-	// Lookup key
-	var key interface{}
+	// Decode signature
+	token.Signature, err = p.DecodeSegment(parts[2])
+	if err != nil {
+		return token, newError("could not base64 decode signature", ErrTokenMalformed, err)
+	}
+	text := strings.Join(parts[0:2], ".")
+
+	// Lookup key(s)
 	if keyFunc == nil {
 		// keyFunc was not provided.  short circuiting validation
 		return token, newError("no keyfunc was provided", ErrTokenUnverifiable)
 	}
-	if key, err = keyFunc(token); err != nil {
-		return token, newError("error while executing keyfunc", ErrTokenUnverifiable, err)
-	}
 
-	// Decode signature
-	token.Signature, err = p.DecodeSegment(parts[2])
+	got, err := keyFunc(token)
 	if err != nil {
-		return token, newError("could not base64 decode signature", ErrTokenMalformed, err)
+		return token, newError("error while executing keyfunc", ErrTokenUnverifiable, err)
 	}
 
-	// Perform signature validation
-	if err = token.Method.Verify(strings.Join(parts[0:2], "."), token.Signature, key); err != nil {
+	switch have := got.(type) {
+	case VerificationKeySet:
+		if len(have.Keys) == 0 {
+			return token, newError("keyfunc returned empty verification key set", ErrTokenUnverifiable)
+		}
+		// Iterate through keys and verify signature, skipping the rest when a match is found.
+		// Return the last error if no match is found.
+		for _, key := range have.Keys {
+			if err = token.Method.Verify(text, token.Signature, key); err == nil {
+				break
+			}
+		}
+	default:
+		err = token.Method.Verify(text, token.Signature, have)
+	}
+	if err != nil {
 		return token, newError("", ErrTokenSignatureInvalid, err)
 	}
 

parser_test.go

@@ -28,6 +28,25 @@ var (
 	emptyKeyFunc           jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) { return nil, nil }
 	errorKeyFunc           jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) { return nil, errKeyFuncError }
 	nilKeyFunc             jwt.Keyfunc = nil
+	multipleZeroKeyFunc    jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) { return []interface{}{}, nil }
+	multipleEmptyKeyFunc   jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) {
+		return jwt.VerificationKeySet{Keys: []jwt.VerificationKey{nil, nil}}, nil
+	}
+	multipleVerificationKeysFunc jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) {
+		return []jwt.VerificationKey{jwtTestDefaultKey, jwtTestEC256PublicKey}, nil
+	}
+	multipleLastKeyFunc jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) {
+		return jwt.VerificationKeySet{Keys: []jwt.VerificationKey{jwtTestEC256PublicKey, jwtTestDefaultKey}}, nil
+	}
+	multipleFirstKeyFunc jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) {
+		return jwt.VerificationKeySet{Keys: []jwt.VerificationKey{jwtTestDefaultKey, jwtTestEC256PublicKey}}, nil
+	}
+	multipleAltTypedKeyFunc jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) {
+		return jwt.VerificationKeySet{Keys: []jwt.VerificationKey{jwtTestDefaultKey, jwtTestDefaultKey}}, nil
+	}
+	emptyVerificationKeySetFunc jwt.Keyfunc = func(t *jwt.Token) (interface{}, error) {
+		return jwt.VerificationKeySet{}, nil
+	}
 )
 
 func init() {
@@ -94,6 +113,46 @@ var jwtTestData = []struct {
 		nil,
 		jwt.SigningMethodRS256,
 	},
+	{
+		"multiple keys, last matches",
+		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",
+		multipleLastKeyFunc,
+		jwt.MapClaims{"foo": "bar"},
+		true,
+		nil,
+		nil,
+		jwt.SigningMethodRS256,
+	},
+	{
+		"multiple keys not []interface{} type, all match",
+		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",
+		multipleAltTypedKeyFunc,
+		jwt.MapClaims{"foo": "bar"},
+		true,
+		nil,
+		nil,
+		jwt.SigningMethodRS256,
+	},
+	{
+		"multiple keys, first matches",
+		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",
+		multipleFirstKeyFunc,
+		jwt.MapClaims{"foo": "bar"},
+		true,
+		nil,
+		nil,
+		jwt.SigningMethodRS256,
+	},
+	{
+		"public keys slice, not allowed",
+		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",
+		multipleVerificationKeysFunc,
+		jwt.MapClaims{"foo": "bar"},
+		false,
+		[]error{jwt.ErrTokenSignatureInvalid},
+		nil,
+		jwt.SigningMethodRS256,
+	},
 	{
 		"basic expired",
 		"", // autogen
@@ -154,6 +213,36 @@ var jwtTestData = []struct {
 		nil,
 		jwt.SigningMethodRS256,
 	},
+	{
+		"multiple nokey",
+		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",
+		multipleEmptyKeyFunc,
+		jwt.MapClaims{"foo": "bar"},
+		false,
+		[]error{jwt.ErrTokenSignatureInvalid},
+		nil,
+		jwt.SigningMethodRS256,
+	},
+	{
+		"empty verification key set",
+		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",
+		emptyVerificationKeySetFunc,
+		jwt.MapClaims{"foo": "bar"},
+		false,
+		[]error{jwt.ErrTokenUnverifiable},
+		nil,
+		jwt.SigningMethodRS256,
+	},
+	{
+		"zero length key list",
+		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",
+		multipleZeroKeyFunc,
+		jwt.MapClaims{"foo": "bar"},
+		false,
+		[]error{jwt.ErrTokenSignatureInvalid},
+		nil,
+		jwt.SigningMethodRS256,
+	},
 	{
 		"basic errorkey",
 		"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJmb28iOiJiYXIifQ.FhkiHkoESI_cG3NPigFrxEk9Z60_oXrOT2vGm9Pn6RDgYNovYORQmmA0zs1AoAOf09ly2Nx2YAg6ABqAYga1AcMFkJljwxTT5fYphTuqpWdy4BELeSYJx5Ty2gmr8e7RonuUztrdD5WfPqLKMm1Ozp_T6zALpRmwTIW0QPnaBXaQD90FplAg46Iy1UlDKr-Eupy0i5SLch5Q-p2ZpaL_5fnTIUDlxC3pWhJTyx_71qDI-mAA_5lE_VdroOeflG56sSmDxopPEG3bFlSu1eowyBfxtu0_CuVd-M42RU75Zc4Gsj6uV77MBtbMrf4_7M_NUTSgoIF3fRqxrj0NzihIBg",

token.go

@@ -1,6 +1,7 @@
 package jwt
 
 import (
+	"crypto"
 	"encoding/base64"
 	"encoding/json"
 )
@@ -9,8 +10,21 @@ import (
 // the key for verification.  The function receives the parsed, but unverified
 // Token.  This allows you to use properties in the Header of the token (such as
 // `kid`) to identify which key to use.
+//
+// The returned interface{} may be a single key or a PublicKeyset containing
+// multiple keys.
 type Keyfunc func(*Token) (interface{}, error)
 
+// VerificationKey represents a public or secret key for verifying a token's signature.
+type VerificationKey interface {
+	crypto.PublicKey | []uint8
+}
+
+// VerificationKeySet is a set of public or secret keys. It is used by the parser to verify a token.
+type VerificationKeySet struct {
+	Keys []VerificationKey
+}
+
 // Token represents a JWT Token.  Different fields will be used depending on
 // whether you're creating or parsing/verifying a token.
 type Token struct {