Documentation about pgp signing of Eclipse plugins

iloveeclipse commented 2 years ago

Follow up on my questions in https://www.eclipse.org/lists/p2-dev/msg05945.html.

Initial issue is https://github.com/spotbugs/spotbugs/issues/2008.

As a small open source progect spotbugs doesn't have resources to provide valid certificates for signing plugins, so we are looking for documentation how we could sign Eclipse plugins with pgp.

It seems there is no documentation available, and various pointers given aren't complete or enough for 3rd party developers. The best source so far is the following bug from Ed : https://gitlab.eclipse.org/eclipse-wg/ide-wg/eclipseide.org/-/issues/11.

Would be great to have an official Eclipse help article (shipped with SDK) which explains step by step following :

prerequisites (which Eclipse version supports pgp to which extent)
build requirements (which tooling needed, on which platform etc)
instructions for signing itself (command line etc)
how to sign already existing p2 artifacts (update site produced by other, non-tycho build)
which side effects ot has on compatibility with old Eclipse platforms (can pgp signed bundle be installed on older Eclipse that doesn't know anything about pgp)

merks commented 2 years ago

My sense is that installing PGP content into any < Eclipse 4.23 is rather problematic.

To do PGP signing, you'll need gpg installed. I use the one that came with git. I expect every build server has that too.

Not that I'm suggesting it's a better way, but it's possible to generate a self-signed x509 certificate and just use that too. I tried that with these instructions:

https://lists.gnupg.org/pipermail/gnupg-devel/2011-March/025989.html

The user will be prompted to approve such an "unrooted" certificate in the same way as is the case for a PGP key, and even in the same dialog. On the plus side, this works on all versions of Eclipse and you can keep doing the build how you are doing it now.

If you don't use Tycho, you'll have to do stuff like this to create the *.asc files:

https://www.benmccann.com/creating-asc-signature-files-with-gpg/

And you'll need to get the key and signature properties into the artifacts.xml like in this example:

https://github.com/eclipse/tycho/issues/872

    <artifact classifier="osgi.bundle" id="org.objectweb.asm" version="9.3.0">
      <properties size="12">
        <property name="maven-groupId" value="org.ow2.asm"/>
        <property name="maven-artifactId" value="asm"/>
        <property name="maven-version" value="9.3"/>
        <property name="maven-repository" value="central"/>
        <property name="maven-type" value="jar"/>
        <property name="download.size" value="122176"/>
        <property name="artifact.size" value="122176"/>
        <property name="download.md5" value="e1c3b96035117ab516ffe0de9bd696e0"/>
        <property name="download.checksum.md5" value="e1c3b96035117ab516ffe0de9bd696e0"/>
        <property name="download.checksum.sha-256" value="1263369b59e29c943918de11d6d6152e2ec6085ce63e5710516f8c67d368e4bc"/>
        <property name="pgp.signatures" value="-----BEGIN PGP SIGNATURE-----&#10;&#10;iQGzBAABCAAdFiEEXONvkY2X+4JrdhoCGmZnOeZvPwcFAmJSsl8ACgkQGmZnOeZv&#10;Pwe+ZAwApzYOMaSL+2Y6O4mF8x/Kw32KTxKtg/4AGpwQEnW3LGAXVOGAHvVhsDoh&#10;5mM+uBKSx/cpGVK/jahIj0E+TFgLj0HmpLql232MKvnrL4bpjUd/YKb+0PkY8ZV7&#10;f+yt+6hcjhjHaiJa9ejGVbxntxxGy+HdZoUYYC/ijDiRmcdyTIMkq1UzinrL7jFb&#10;ycNp4oqwWfP2d8AfMRKeMHT8PazZSIMHm1Y0WCPkXuk+A+izxZAC/YI4nVu6S0Cx&#10;rSekszwvChZNDUufX/7M7YH8aJlvagQ9MfeMEyVmwPIlmUaijAyrwTbYGkmTJspG&#10;2WshBGweWw739Iqv8OHeQu67mPZ5EI+P13uEpilMm7y5V10K9NGMjEjeXZcJ9dST&#10;l3Xl7qvyxZGrtOUGENN7Skx0KcC+6nHAfodyZ9OBQFfsOTKJwNeC62LPIISHBbVR&#10;31CDW2amQmhmIFzLhyIh8DrFU9pWuZUZw7Xg7pHXQ5JXElFdxWsv6Fd7j8oNNR6a&#10;idY6vFbz&#10;=u3wh&#10;-----END PGP SIGNATURE-----&#10;"/>
        <property name="pgp.publicKeys" value="-----BEGIN PGP PUBLIC KEY BLOCK-----&#10;&#10;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&#10;OFY5TF2oaKTKRPXskg==&#10;=skba&#10;-----END PGP PUBLIC KEY BLOCK-----&#10;"/>
      </properties>
    </artifact>

mickaelistria commented 2 years ago

There is https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_pgp.html . What do you think is missing particularly?

iloveeclipse commented 2 years ago

@mickaelistria : see the bug description about what is missing. I see no answers in the documentation link you've provided.

mickaelistria commented 2 years ago

Where should such documentation be located? How to produce signatures in a build flow doesn't really belong to p2 per se (although p2 publisher could host a PGPSignatureAdvice to produce them more easily via API but that would be another topic), similarly to how to use jarsigner and integrate it in some build.

iloveeclipse commented 2 years ago

We provide a support for a feature without anyone ever explained how that feature could be actually implemented, that is at least strange. So far the docu only says that you can use pgp signed bundles from 4.21 and gives some insights into some internal design of the feature, but it doesn't explain at all how the user can produce the signed bundles.

I'm probably a first client trying to use that feature and I have no clue at all (except answers on mailing lists on my questions).

I personally would expect that on the same Eclipse help page a simple step by step example is given: how one can produce a signed bundle, using concrete commands, and limitation of the current solution is also explained. If you or someone else did that during implementation of the feature (I think so), that should be not a big deal to add this info to the help, right?

Reading comments from Ed / Stephan I assume users should also have been informed by the help about following limitations:

the only way to add pgp support to bundles seem to be to build with some extra tycho configuration or use some tycho command (neither one is explained)
manual signing seem to be possible too, again undocumented how it can be done / which format of related files is expected etc
it works only from 4.23+ release (not from 4.21!) due some bugs or limitations in previous releases
older releases do not support pgp so the pgp solution can be recommended only to those who deploy on 4.23+ platforms.

Side note: searching the help for "Using PGP signatures in p2" doesn't deliver any relevant matches, the direct link https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_pgp.html doesn't have a bread crumb and doesn't show up in the "Content" tree structure on the left side if clicking on the "Link with contents" button - it looks like there is something missing in the help contribution. Compare that with the jarsigner link: https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/bundle_security.html?cp=2_0_3_7_1

eclipse-equinox / p2

Documentation about pgp signing of Eclipse plugins #32