Skip to content

feat(alg): Add ES512 support #566

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 3 commits into
base: main
Choose a base branch
from
Open

feat(alg): Add ES512 support #566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff8912b
feat(alg): Add ES512 support
Ninos May 25, 2024
1e2c792
style(types): Strict types + phpdoc
Ninos May 25, 2024
a493f16
Merge branch 'main' into alg-es512
bshaffer Apr 9, 2025
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
3 changes: 2 additions & 1 deletion composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@
],
"license": "BSD-3-Clause",
"require": {
"php": "^8.0"
"php": "^8.0",
"ext-openssl": "*"
Copy link
Collaborator

Choose a reason for hiding this comment

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

Why would we require the extension? This would block existing users from upgrading who are not currently using openssl.

},
"suggest": {
"paragonie/sodium_compat": "Support EdDSA (Ed25519) signatures when libsodium is not present",
Expand Down
59 changes: 29 additions & 30 deletions src/JWT.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ class JWT
*
* @var int
*/
public static $leeway = 0;
public static int $leeway = 0;

/**
* Allow the current timestamp to be specified.
Expand All @@ -47,15 +47,16 @@ class JWT
*
* @var ?int
*/
public static $timestamp = null;
public static ?int $timestamp = null;

/**
* @var array<string, string[]>
*/
public static $supported_algs = [
'ES384' => ['openssl', 'SHA384'],
public static array $supported_algs = [
'ES256' => ['openssl', 'SHA256'],
'ES256K' => ['openssl', 'SHA256'],
'ES384' => ['openssl', 'SHA384'],
'ES512' => ['openssl', 'SHA512'],
'HS256' => ['hash_hmac', 'SHA256'],
'HS384' => ['hash_hmac', 'SHA384'],
'HS512' => ['hash_hmac', 'SHA512'],
Expand All @@ -75,10 +76,10 @@ class JWT
* the public key.
* Each Key object contains an algorithm and
* matching key.
* Supported algorithms are 'ES384','ES256',
* Supported algorithms are 'ES256', 'ES256K', 'ES384', 'ES512',
* 'HS256', 'HS384', 'HS512', 'RS256', 'RS384'
* and 'RS512'.
* @param stdClass $headers Optional. Populates stdClass with headers.
* @param stdClass|null $headers Optional. Populates stdClass with headers.
*
* @return stdClass The JWT's payload as a PHP object
*
Expand All @@ -95,7 +96,7 @@ class JWT
*/
public static function decode(
string $jwt,
$keyOrKeyArray,
Key|ArrayAccess|array $keyOrKeyArray,
?stdClass &$headers = null
): stdClass {
// Validate JWT
Expand Down Expand Up @@ -142,8 +143,8 @@ public static function decode(
// See issue #351
throw new UnexpectedValueException('Incorrect key for this algorithm');
}
if (\in_array($header->alg, ['ES256', 'ES256K', 'ES384'], true)) {
// OpenSSL expects an ASN.1 DER sequence for ES256/ES256K/ES384 signatures
if (\in_array($header->alg, ['ES256', 'ES256K', 'ES384', 'ES512'], true)) {
// OpenSSL expects an ASN.1 DER sequence for ES256/ES256K/ES384/ES512 signatures
$sig = self::signatureToDER($sig);
}
if (!self::verify("{$headb64}.{$bodyb64}", $sig, $key->getKeyMaterial(), $header->alg)) {
Expand Down Expand Up @@ -184,12 +185,12 @@ public static function decode(
/**
* Converts and signs a PHP array into a JWT string.
*
* @param array<mixed> $payload PHP array
* @param string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate $key The secret key.
Copy link
Collaborator

Choose a reason for hiding this comment

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

why are you removing resource from the PHPDoc? That would be a breaking change

* @param string $alg Supported algorithms are 'ES384','ES256', 'ES256K', 'HS256',
* 'HS384', 'HS512', 'RS256', 'RS384', and 'RS512'
* @param string $keyId
* @param array<string, string> $head An array with header elements to attach
* @param array $payload PHP array
* @param string|array|OpenSSLAsymmetricKey|OpenSSLCertificate $key The secret key.
* @param string $alg Supported algorithms are 'ES256', 'ES256K', 'ES384', 'ES512',
* 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', and 'RS512'
* @param string|null $keyId
* @param array<string, string>|null $head An array with header elements to attach
*
* @return string A signed JWT
*
Expand All @@ -198,7 +199,7 @@ public static function decode(
*/
public static function encode(
array $payload,
$key,
string|array|OpenSSLAsymmetricKey|OpenSSLCertificate $key,
Copy link
Collaborator

Choose a reason for hiding this comment

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

this would be a breaking change for anyone supplying type resource

string $alg,
?string $keyId = null,
?array $head = null
Expand Down Expand Up @@ -226,17 +227,17 @@ public static function encode(
* Sign a string with a given key and algorithm.
*
* @param string $msg The message to sign
* @param string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate $key The secret key.
* @param string $alg Supported algorithms are 'EdDSA', 'ES384', 'ES256', 'ES256K', 'HS256',
* 'HS384', 'HS512', 'RS256', 'RS384', and 'RS512'
* @param string|array|OpenSSLAsymmetricKey|OpenSSLCertificate $key The secret key.
* @param string $alg Supported algorithms are 'EdDSA', 'ES256', 'ES256K', 'ES384', 'ES512',
* 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', and 'RS512'
*
* @return string An encrypted message
*
* @throws DomainException Unsupported algorithm or bad key was specified
*/
public static function sign(
string $msg,
$key,
string|array|OpenSSLAsymmetricKey|OpenSSLCertificate $key,
string $alg
): string {
if (empty(static::$supported_algs[$alg])) {
Expand All @@ -262,6 +263,8 @@ public static function sign(
$signature = self::signatureFromDER($signature, 256);
} elseif ($alg === 'ES384') {
$signature = self::signatureFromDER($signature, 384);
} elseif ($alg === 'ES512') {
$signature = self::signatureFromDER($signature, 512);
Copy link
Collaborator

Choose a reason for hiding this comment

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

am I right in understanding this is the only real code change (other than adding ES512 to the list of supported algorithms)? If so, then this is a small enough change, but I would like to see some tests! See here for examples

php-jwt/tests/JWTTest.php

Line 487 in 27179e1

public function provideEncodeDecode()

}
return $signature;
case 'sodium_crypto':
Expand Down Expand Up @@ -293,7 +296,7 @@ public static function sign(
*
* @param string $msg The original message (header and body)
* @param string $signature The original signature
* @param string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate $keyMaterial For Ed*, ES*, HS*, a string key works. for RS*, must be an instance of OpenSSLAsymmetricKey
* @param string|array|OpenSSLAsymmetricKey|OpenSSLCertificate $keyMaterial For Ed*, ES*, HS*, a string key works. for RS*, must be an instance of OpenSSLAsymmetricKey
* @param string $alg The algorithm
*
* @return bool
Expand All @@ -303,7 +306,7 @@ public static function sign(
private static function verify(
string $msg,
string $signature,
$keyMaterial,
string|array|OpenSSLAsymmetricKey|OpenSSLCertificate $keyMaterial,
string $alg
): bool {
if (empty(static::$supported_algs[$alg])) {
Expand Down Expand Up @@ -364,7 +367,7 @@ private static function verify(
*
* @throws DomainException Provided string was invalid JSON
*/
public static function jsonDecode(string $input)
public static function jsonDecode(string $input): mixed
{
$obj = \json_decode($input, false, 512, JSON_BIGINT_AS_STRING);

Expand All @@ -379,7 +382,7 @@ public static function jsonDecode(string $input)
/**
* Encode a PHP array into a JSON string.
*
* @param array<mixed> $input A PHP array
* @param array $input A PHP array
*
* @return string JSON representation of the PHP array
*
Expand Down Expand Up @@ -457,7 +460,7 @@ public static function urlsafeB64Encode(string $input): string
* @return Key
*/
private static function getKey(
$keyOrKeyArray,
Key|ArrayAccess|array $keyOrKeyArray,
?string $kid
): Key {
if ($keyOrKeyArray instanceof Key) {
Expand Down Expand Up @@ -519,11 +522,7 @@ private static function handleJsonError(int $errno): void
JSON_ERROR_SYNTAX => 'Syntax error, malformed JSON',
JSON_ERROR_UTF8 => 'Malformed UTF-8 characters' //PHP >= 5.3.3
];
throw new DomainException(
isset($messages[$errno])
? $messages[$errno]
: 'Unknown JSON error: ' . $errno
);
throw new DomainException($messages[$errno] ?? 'Unknown JSON error: ' . $errno);
}

/**
Expand Down