Publish PGP signatures for `pie.phar`

[PhrozenByte]

Currently PIE recommends using gh attestation verify from the GitHub CLI to verify a downloaded pie.phar. However, I do not have GitHub CLI installed, nor do I wish to install it. Additionally, relying solely on GitHub attestations creates a form of vendor lock-in.

A more portable and well-established alternative would be to provide a standard PGP signature alongside the release asset. Therefore, I would like to suggest publishing a public PGP key and including a pie.phar.asc signature file next to each pie.phar release to allow independent and widely compatible verification. This is common practice for other PHAR projects, such as Composer or PHIVE.

Alternatively, projects like PHPUnit use Sigstore; while I personally prefer PGP for its simplicity and wider availability, Sigstore would also be a viable option.

Besides: Great project, thank you! ❤️

[asgrim]

PIE doesn't require GitHub CLI, there is a fallback mechanism built in to pie self-verify and pie self-update (as long as openssl ext is already installed), if you don't have gh installed.

Practically, since the phar is only ever built in CI and attestations generated there and then, it is actually slightly more secure. In order for me to sign the phar with my GPG key, I would have to download the phar, sign it, and upload the signature; there is technically (although unlikely) possibility for vulnerabilities there.

The attestation generated isn't specific to GH, it is just a Sigstore attestation anyway, but GH is just the generator. The ThePHPF/attestation library is what we're using for this, and keen to improve this library separately and address vendor lock-in concerns 👍

[PhrozenByte]

PIE doesn't require GitHub CLI, there is a fallback mechanism built in to pie self-verify and pie self-update (as long as openssl ext is already installed), if you don't have gh installed.

Assuming an attacker somehow managed to tamper with the downloaded pie.phar (e.g., in transfer, or GitHub's release asset storage is compromised), this wouldn't actually verify that the pie.phar is legit, right? As far as I understand, it only verifies integrity of updates once PIE is already installed and trusted, not the initial pie.phar download.

Practically, since the phar is only ever built in CI and attestations generated there and then, it is actually slightly more secure. In order for me to sign the phar with my GPG key, I would have to download the phar, sign it, and upload the signature; there is technically (although unlikely) possibility for vulnerabilities there.

There's indeed an ongoing universal debate about whether manual signing or fully automated CI-based signing is "more secure", but to be honest, that isn't really my concern here. Both models have Pros and Cons, and I think they are equally valid.

If manual signing is undesirable, you can also generate a dedicated PGP key used exclusively for release signing, publish the public key separately (preferably also on public key servers), and store the private key as an Actions secret so it never leaves CI. This is how many projects handle fully automated PHAR or tarball signing.

The attestation generated isn't specific to GH, it is just a Sigstore attestation anyway, but GH is just the generator.

Is there a way to access PIE's Sigstore attestation artifacts separately (like with PHPUnit)? I'm not very familiar with GitHub's API in this regard. That would already solve most of my concerns, assuming the artifacts can be used to verify the pie.phar's legitimacy with standard tools (or PIE-own tools).

[asgrim]

Assuming an attacker somehow managed to tamper with the downloaded pie.phar (e.g., in transfer, or GitHub's release asset storage is compromised), this wouldn't actually verify that the pie.phar is legit, right? As far as I understand, it only verifies integrity of updates once PIE is already installed and trusted, not the initial pie.phar download.

In the pie self-update command, PIE does not replace the existing PIE until it has verified the newly downloaded file. e.g. it'll download the new phar to /tmp/new-pie.phar (not an exact name, can't remember it off my head), then do either gh attestation verify --owner=php /tmp/new-pie.phar or use the ThePHPF/Attestation library as a fallback if gh is not available; once it is verified and the signature checks out, it will move /tmp/new-pie.phar to the currently running file (e.g. /usr/local/bin/pie or wherever you are running it).

So yes; it does verify the pie.phar you are trying to update to is genuine (specifically: what we are checking for is that the pie.phar you possess was built in the "official" PHP GitHub CI pipeline, and has not been tampered with) before PIE is installed.

If you have downloaded a pie.phar manually (i.e. you're not using pie self-update), you can run either pie self-verify after downloading it, which verifies itself using the same mechanism described, or you can separately run gh attestation verify --owner=php your-pie.phar (if you have it).

If manual signing is undesirable, you can also generate a dedicated PGP key used exclusively for release signing, publish the public key separately (preferably also on public key servers), and store the private key as an Actions secret so it never leaves CI. This is how many projects handle fully automated PHAR or tarball signing.

This is something I've used before (and was automated thanks to laminas/automatic-releases); but this approach is no better or worse than using GitHub's attestation action; ultimately GitHub holds the keys, and if compromised, that will be the weak link in either case. In fact; I had originally planned to use a GPG private key in secrets in this manner, but I had discovered the Attestation feature, which has more benefits than regular GPG signing.

Don't get me wrong, I'm personally a fan of GPG, but I always felt storing the private key as a secret was a less than ideal approach (since, you have to trust the host - GitHub in this case - does not somehow leak that key). That said, it was an adequate solution, assuming good faith from GitHub; but the GH Attestations functionality we felt packaged up a much more elegant solution, using open standards (Sigstore). This makes me quite reluctant to add a GPG signature to PIE, when we already have an arguably superior approach implemented.

Is there a way to access PIE's Sigstore attestation artifacts separately (like with PHPUnit)? I'm not very familiar with GitHub's API in this regard. That would already solve most of my concerns, assuming the artifacts can be used to verify the pie.phar's legitimacy with standard tools (or PIE-own tools).

You can download the attestation (example: https://github.com/php/pie/attestations/13387661, see also Attestations API), but it is hosted on GitHub - just like PHPUnit's is; the releases attestation (the JSON file attached to the releases page you linked to) is new, and related to Immutable releases feature, rather than verifying provenance for build artifacts (which is what PIE uses). PIE has, in fact, recently enabled Immutable releases, so the release attestation will exist on future releases (example: https://github.com/php/pie/releases/tag/1.3.0-rc.1) - but this is NOT currently checked by pie self-update.

The GitHub Attestation feature, from the perspective of "the verifier" (rather than us, "the maintainers"), there are indeed a few GitHub specific things:

• where the attestation document(s) are stored; in this case, that is our decision. We opted to use GH Attestation, rather than any separate Sigstore based system; this is for convenience, and makes our lives as maintainers easier
• how you verify the provenance of that attestation document; whilst you CAN use the gh tool, you don't have to. The attestation document itself is not in some proprietary GitHub format; it is a Sigstore formatted document, and you could use any compatible tooling to verify it. This is how we were able to build the library.
• the "trusted root" manifest. This contains certificate authorities from both Sigstore, and GitHub. In theory, you could specify your own trusted root manifest; although the library doesn't support that yet. That is an improvement that could be worked on separately (feel free to open an issue if that's something useful! https://github.com/ThePHPF/attestation/issues)

Apart from those parts (I think, off my head), the actual verification is intended to be standardised.

[asgrim]

Oh - incidentally, as a side note, I do sign my commits and tags etc; so if you were very paranoid, you could verify with for example git tag -v 1.3.0-rc.2; but this doesn't really help when all you have a is a pie.phar :)

[PhrozenByte]

Thanks for your detailed answer! This clarifies a lot ❤️

If you have downloaded a pie.phar manually (i.e. you're not using pie self-update), you can run either pie self-verify after downloading it, which verifies itself using the same mechanism described, or you can separately run gh attestation verify --owner=php your-pie.phar (if you have it).

If an attacker already tampered with the pie.phar I just downloaded, he can easily make pie self-verify print whatever he wants. Verification can only be done with tooling independent of what I've just downloaded. pie self-update is such independent tooling. gh attestation is, too. But pie self-verify is not. So it can't be a replacement for gh attestation - or what am I missing?

My first concern is solely focused on user experience: PIE currently requires me to install GitHub CLI to verify that a downloaded pie.phar is genuine. I don't have GitHub CLI installed. How do I verify that the pie.phar I downloaded is genuine without GitHub CLI? pie self-verify unfortunately isn't the answer.

With an .asc I would run gpg --recv-key with the full key fingerprint I've obtained separately earlier, and gpg --verify pie.phar.asc pie.phar. That's it. GnuPG is standard tooling available basically everywhere. GitHub CLI is not. I understand that one can, in theory, verify a pie.phar without GitHub CLI, but how do I actually do that using just standard tooling?

In fact; I had originally planned to use a GPG private key in secrets in this manner, but I had discovered the Attestation feature, which has more benefits than regular GPG signing. […]
This makes me quite reluctant to add a GPG signature to PIE, when we already have an arguably superior approach implemented. […]
The GitHub Attestation feature, from the perspective of "the verifier" (rather than us, "the maintainers"), there are indeed a few GitHub specific things: […] the "trusted root" manifest. This contains certificate authorities from both Sigstore, and GitHub. In theory, you could specify your own trusted root manifest; although the library doesn't support that yet.

My second concern is about this matter and what I call "vendor lock-in". As long as you're using GitHub's identity provider, you give GitHub full authority over PIE. GitHub decides what a genuine PIE release is - and not you (resp. the PIE team). I'm not concerned about the technology.

Let's assume Microsoft shuts down GitHub tomorrow. Switching to a different hoster is easy, so you do that. But how can users verify that a pie.phar they found on some alleged (!) new official website is actually PIE? As far as I understand, you don't sign PIE with your (or: "the project's") key, but are rather relying on GitHub's identity provider. This chain of trust can go away any time. PIE needs its own (or that of the PHP project, or The PHP Foundation, or whatever, just no 3rd party) trusted root.

With a PGP key you wouldn't do that. Yes, you trust GitHub with a private subkey, but the validity of that subkey is limited (the more limited while still being feasible the better) and you, and only you (or: "the project"), have the primary key. So, if GitHub goes away, you just sign your new pie.phar with a different subkey of the same primary key and users can easily verify that the pie.phar they found is indeed genuine.

As far as I understand reducing the required trust in e.g. GitHub is the whole idea of Sigstore and why the technology can indeed be considered superior, but as long as you're using GitHub's identity provider you actually make things worse than with a classic PGP key. But maybe I understand something wrong or totally miss something, I'm by far no expert in this matter, so please correct me then.