add key object support in v5

Author: bshaffer

.github/actions/entrypoint.sh

@@ -5,6 +5,7 @@ apt-get install -y --no-install-recommends \
     git \
     zip \
     curl \
+    ca-certificates \
     unzip \
     wget
 

README.md

@@ -27,6 +27,7 @@ Example
 -------
 ```php
 use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
 
 $key = "example_key";
 $payload = array(
@@ -43,7 +44,7 @@ $payload = array(
  * for a list of spec-compliant algorithms.
  */
 $jwt = JWT::encode($payload, $key);
-$decoded = JWT::decode($jwt, $key, array('HS256'));
+$decoded = JWT::decode($jwt, new Key($key, 'HS256'));
 
 print_r($decoded);
 
@@ -62,12 +63,13 @@ $decoded_array = (array) $decoded;
  * Source: http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#nbfDef
  */
 JWT::$leeway = 60; // $leeway in seconds
-$decoded = JWT::decode($jwt, $key, array('HS256'));
+$decoded = JWT::decode($jwt, new Key($key, 'HS256'));
 ```
 Example with RS256 (openssl)
 ----------------------------
 ```php
 use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
 
 $privateKey = <<<EOD
 -----BEGIN RSA PRIVATE KEY-----
@@ -106,7 +108,7 @@ $payload = array(
 $jwt = JWT::encode($payload, $privateKey, 'RS256');
 echo "Encode:\n" . print_r($jwt, true) . "\n";
 
-$decoded = JWT::decode($jwt, $publicKey, array('RS256'));
+$decoded = JWT::decode($jwt, new Key($publicKey, 'RS256'));
 
 /*
  NOTE: This will now be an object instead of an associative array. To get
@@ -121,6 +123,9 @@ Example with a passphrase
 -------------------------
 
 ```php
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
+
 // Your passphrase
 $passphrase = '[YOUR_PASSPHRASE]';
 
@@ -147,14 +152,15 @@ echo "Encode:\n" . print_r($jwt, true) . "\n";
 // Get public key from the private key, or pull from from a file.
 $publicKey = openssl_pkey_get_details($privateKey)['key'];
 
-$decoded = JWT::decode($jwt, $publicKey, array('RS256'));
+$decoded = JWT::decode($jwt, new Key($publicKey, 'RS256'));
 echo "Decode:\n" . print_r((array) $decoded, true) . "\n";
 ```
 
 Example with EdDSA (libsodium and Ed25519 signature)
 ----------------------------
 ```php
 use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
 
 // Public and private keys are expected to be Base64 encoded. The last
 // non-empty line is used so that keys can be generated with
@@ -177,7 +183,7 @@ $payload = array(
 $jwt = JWT::encode($payload, $privateKey, 'EdDSA');
 echo "Encode:\n" . print_r($jwt, true) . "\n";
 
-$decoded = JWT::decode($jwt, $publicKey, array('EdDSA'));
+$decoded = JWT::decode($jwt, new Key($publicKey, 'EdDSA'));
 echo "Decode:\n" . print_r((array) $decoded, true) . "\n";
 ````
 
@@ -194,7 +200,7 @@ $jwks = ['keys' => []];
 
 // JWK::parseKeySet($jwks) returns an associative array of **kid** to private
 // key. Pass this as the second parameter to JWT::decode.
-JWT::decode($payload, JWK::parseKeySet($jwks), $supportedAlgorithm);
+JWT::decode($payload, JWK::parseKeySet($jwks));
 ```
 
 Changelog

src/JWT.php

@@ -61,11 +61,13 @@ class JWT
      * Decodes a JWT string into a PHP object.
      *
      * @param string                    $jwt            The JWT
-     * @param string|array|resource     $key            The key, or map of keys.
+     * @param Key|array<Key>            $keyOrKeyArray  The Key or array of Key objects.
      *                                                  If the algorithm used is asymmetric, this is the public key
-     * @param array                     $allowed_algs   List of supported verification algorithms
+     *                                                  Each Key object contains an algorithm and matching key.
      *                                                  Supported algorithms are 'ES384','ES256', 'HS256', 'HS384',
      *                                                  'HS512', 'RS256', 'RS384', and 'RS512'
+     * @param array                     $allowed_algs   [DEPRECATED] List of supported verification algorithms. Only
+     *                                                  should be used for BC.
      *
      * @return object The JWT's payload as a PHP object
      *
@@ -79,11 +81,11 @@ class JWT
      * @uses jsonDecode
      * @uses urlsafeB64Decode
      */
-    public static function decode($jwt, $key, array $allowed_algs = array())
+    public static function decode($jwt, $keyOrKeyArray, array $allowed_algs = array())
     {
         $timestamp = \is_null(static::$timestamp) ? \time() : static::$timestamp;
 
-        if (empty($key)) {
+        if (empty($keyOrKeyArray)) {
             throw new InvalidArgumentException('Key may not be empty');
         }
         $tks = \explode('.', $jwt);
@@ -106,36 +108,32 @@ public static function decode($jwt, $key, array $allowed_algs = array())
         if (empty(static::$supported_algs[$header->alg])) {
             throw new UnexpectedValueException('Algorithm not supported');
         }
-        if (!\in_array($header->alg, $allowed_algs)) {
-            throw new UnexpectedValueException('Algorithm not allowed');
+
+        list($keyMaterial, $algorithm) = self::getKeyMaterialAndAlgorithm(
+            $keyOrKeyArray,
+            empty($header->kid) ? null : $header->kid
+        );
+
+        if (empty($algorithm)) {
+            // Use deprecated "allowed_algs" to determine if the algorithm is supported.
+            // This opens up the possibility of an attack in some implementations.
+            // @see https://github.com/firebase/php-jwt/issues/351
+            if (!\in_array($header->alg, $allowed_algs)) {
+                throw new UnexpectedValueException('Algorithm not allowed');
+            }
+        } else {
+            // Check the algorithm
+            if (!self::constantTimeEquals($algorithm, $header->alg)) {
+                // See issue #351
+                throw new UnexpectedValueException('Incorrect key for this algorithm');
+            }
         }
         if ($header->alg === 'ES256' || $header->alg === 'ES384') {
             // OpenSSL expects an ASN.1 DER sequence for ES256/ES384 signatures
             $sig = self::signatureToDER($sig);
         }
 
-        /** @var Keyring|JWTKey $key */
-        $key = self::getKeyType($key, $allowed_algs);
-        if ($key instanceof Keyring) {
-            if (isset($header->kid)) {
-                if (!isset($key[$header->kid])) {
-                    throw new UnexpectedValueException('"kid" invalid, unable to lookup correct key');
-                }
-                $key = $key[$header->kid];
-            } else {
-                throw new UnexpectedValueException('"kid" empty, unable to lookup correct key');
-            }
-        }
-        if (!($key instanceof JWTKey)) {
-            throw new UnexpectedValueException('$key should be an instance of JWTKey');
-        }
-
-        // Check the signature
-        if (!$key->isValidForAlg($header->alg)) {
-            // See issue #351
-            throw new UnexpectedValueException('Incorrect key for this algorithm');
-        }
-        if (!static::verify("$headb64.$bodyb64", $sig, $key->getKeyMaterial(), $header->alg)) {
+        if (!static::verify("$headb64.$bodyb64", $sig, $keyMaterial, $header->alg)) {
             throw new SignatureInvalidException('Signature verification failed');
         }
 
@@ -385,6 +383,47 @@ public static function urlsafeB64Encode($input)
         return \str_replace('=', '', \strtr(\base64_encode($input), '+/', '-_'));
     }
 
+
+    /**
+     * Determine if an algorithm has been provided for each Key
+     *
+     * @param string|array $keyOrKeyArray
+     *
+     * @return an array containing the keyMaterial and algorithm
+     */
+    private static function getKeyMaterialAndAlgorithm($keyOrKeyArray, $kid = null)
+    {
+        if (is_string($keyOrKeyArray)) {
+            return [$keyOrKeyArray, null];
+        }
+
+        if ($keyOrKeyArray instanceof Key) {
+            return [$keyOrKeyArray->getKeyMaterial(), $keyOrKeyArray->getAlgorithm()];
+        }
+
+        if (is_array($keyOrKeyArray) || $keyOrKeyArray instanceof ArrayAccess) {
+            if (!isset($kid)) {
+                throw new UnexpectedValueException('"kid" empty, unable to lookup correct key');
+            }
+            if (!isset($keyOrKeyArray[$kid])) {
+                throw new UnexpectedValueException('"kid" invalid, unable to lookup correct key');
+            }
+
+            $key = $keyOrKeyArray[$kid];
+
+            if ($key instanceof Key) {
+                return [$key->getKeyMaterial(), $key->getAlgorithm()];
+            }
+
+            return [$key, null];
+        }
+
+        throw new UnexpectedValueException(
+            '$keyOrKeyArray must be a string key, an array of string keys, '
+            . 'an instance of Firebase\JWT\Key key or an array of Firebase\JWT\Key keys'
+        );
+    }
+
     /**
      * @param string $left
      * @param string $right
@@ -406,29 +445,6 @@ public static function constantTimeEquals($left, $right)
         return ($status === 0);
     }
 
-    /**
-     * @param string|array|ArrayAccess $oldType
-     * @param string[] $algs
-     * @return KeyInterface
-     */
-    public static function getKeyType($oldType, $algs)
-    {
-        if ($oldType instanceof KeyInterface) {
-            return $oldType;
-        }
-        if (is_string($oldType)) {
-            return new JWTKey($oldType, $algs);
-        }
-        if (is_array($oldType) || $oldType instanceof ArrayAccess) {
-            $keyring = new Keyring(array());
-            foreach ($oldType as $kid => $key) {
-                $keyring[$kid] = new JWTKey($key, $algs);
-            }
-            return $keyring;
-        }
-        throw new InvalidArgumentException('Invalid type: Must be string or array');
-    }
-
     /**
      * Helper method to create a JSON error.
      *

src/Key.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Firebase\JWT;
+
+use InvalidArgumentException;
+use OpenSSLAsymmetricKey;
+
+class Key
+{
+    /** @var string $algorithm */
+    private $algorithm;
+
+    /** @var string $keyMaterial */
+    private $keyMaterial;
+
+    /**
+     * @param string|resource $keyMaterial
+     * @param string $algorithm
+     */
+    public function __construct($keyMaterial, $algorithm)
+    {
+        if (
+            !is_string($keyMaterial)
+            && !is_resource($keyMaterial)
+            && !$keyMaterial instanceof OpenSSLAsymmetricKey
+        ) {
+            throw new InvalidArgumentException('Type error: $keyMaterial must be a string, resource, or OpenSSLAsymmetricKey');
+        }
+
+        if (empty($keyMaterial)) {
+            throw new InvalidArgumentException('Type error: $keyMaterial must not be empty');
+        }
+
+        if (!is_string($algorithm)|| empty($keyMaterial)) {
+            throw new InvalidArgumentException('Type error: $algorithm must be a string');
+        }
+        $this->keyMaterial = $keyMaterial;
+        $this->algorithm = $algorithm;
+    }
+
+    /**
+     * Return the algorithm valid for this key
+     *
+     * @return string
+     */
+    public function getAlgorithm()
+    {
+        return $this->algorithm;
+    }
+
+    /**
+     * @return string|resource
+     */
+    public function getKeyMaterial()
+    {
+        return $this->keyMaterial;
+    }
+}