PHP 8.1: Phar: Added OpenSSL-256 and OpenSSL-512 signature algorithms

Phar extension in PHP can be used to package and run a PHP application using a single archive, called a Phar file. These Phar files can contain a signature to ensure it is not corrupted or incomplete.

Note that the integrity checks provided for Phar may not be suitable to avoid supply-chain attacks. While it can detect damaged or incomplete Phar files, it is trivial to modify a Phar archive and remove its integrity checks, rendering these checks fall short.

Phar::setSignatureAlgorithm sets the signature algorithm used in a Phar archive. Unless this value is set, PHP picks SHA256 (SHA1 prior to PHP 8.1) as the signature algorithm.

Phar also supports generating the signature using OpenSSL to generate the signature using a private key, validated with the file key. OpenSSL signatures require the OpenSSL extension enabled.

openssl genrsa -out private.pem 4096
openssl rsa -in private.pem -pubout -out public.pem

$pharFile = 'hello.phar';
$phar = new Phar($pharFile);
$phar->buildFromDirectory('src/');
$phar->setDefaultStub('index.php', '/index.php');

$private_key = file_get_contents("private.pem");
$phar->setSignatureAlgorithm(Phar::OPENSSL, $private_key);

When the Phar file (hello.phar from the example above) is executed, PHP refuses to run the Phar archive unless the public key is present at a file name with suffix .pubkey in the same directory (hello.phar.pubkey from the example).

In PHP 8.1, two new algorithms are introduced: OpenSSL 256 and OpenSSL 512. These two algorithms also require the OpenSSL extension enabled.

New Constants

• Phar::OPENSSL_SHA256 - Assigned 17, sets the signature algorithm to OpenSSL private key signing using SHA512.
• Phar::OPENSSL_SHA512 - Assigned 18, sets the signature algorithm to OpenSSL private key signing using SHA256.

- $phar->setSignatureAlgorithm(Phar::OPENSSL, $private_key);
+ $phar->setSignatureAlgorithm(Phar::OPENSSL_SHA256, $private_key);

Related Changes

• PHP 8.1: Phar: Default signature algorithm changed from SHA1 to SHA256

Backwards Compatibility Impact

Note that the new signature algorithms are not backwards compatible. Any Phar archive created using OPENSSL_SHA256 or OPENSSL_SHA512 will fail to run in PHP versions prior to PHP 8.1. All OPENSSL signatures also require the OpenSSL extension enabled.

Attempting to use a Phar archive with an OPENSSL_SHA256 or OPENSSL_SHA512 signature fails with an UnexpectedValueException exception (when loading use Phar class) or a PharException (on direct execution):

phar "hello.phar" has a broken or unsupported signature in hello.phar:8

---

Implementation