From 43d162f452223f4fecf4c6ea251a1e2e4feda172 Mon Sep 17 00:00:00 2001 From: rugk Date: Fri, 15 Dec 2023 14:17:51 +0100 Subject: [PATCH 1/2] =?UTF-8?q?Created=20doc=20for=20=E2=80=9Chow=20to=20v?= =?UTF-8?q?erify=20and=20how=20to=20do=20release=E2=80=9D=20(release=20doc?= =?UTF-8?q?)=20(WIP)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This documents/should document: * what the signatures are and what they proof * how to verify them * how to build releases (I know more of a maintainer doc, but yeah, I found it a good place here, if you want a separate one feel free) This should also make it easier for other maintainers to create releases or so. @elrido feel free to adjust/push to the branch if you want to have some details fixed. I have left some TODOs of stuff where I am unsure. --- doc/Release.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 doc/Release.md diff --git a/doc/Release.md b/doc/Release.md new file mode 100644 index 00000000..97ec02ff --- /dev/null +++ b/doc/Release.md @@ -0,0 +1,70 @@ +# Release + +## Properties + +### Supply-chain security + +Since [v1.6.2](https://github.com/PrivateBin/PrivateBin/releases/tag/1.6.2) our release assets are [verified with the SLSA framework](https://slsa.dev/). +SLSA stands for „Supply-chain Levels for Software Artifacts”. + +This achieves the following: +1. It ensures no maintainer has gone rogue and has modified/tampered with the source code before “building” the release. +2. It ensures the release is build exactly according to the source as defined by the branch that was used for the release. + This includes the workflow file defining how the release is done itself. +3. Our release should achieve [SLSA build level 3](https://slsa.dev/spec/v1.0/levels#build-l3) as it [runs on GitHub](https://slsa.dev/spec/v1.0/threats). Some more properties [are thus achieved](https://slsa.dev/spec/v1.0/threats). + +That said, here are some caveasts: +* None of our dependencies has any SLSA verification yet (as of Dec 2023) and thus we (cannot) verify any of our own supply chain. + That said, this is mitigated by the fact that the project has not that many dependencies at all. + +For more information [see the corresponding issue](https://github.com/PrivateBin/PrivateBin/issues/1169) and [the GitHub workflow file](/.github/workflows/release.yml). + +#### How to verify + +Git signature for verifying the reproducibility and that a maintainer in posession with that PGP private key created the release with that content: +``` +$ gpg2 --verify PrivateBin-1.2.1.tar.gz.asc # TODO: update for v1.6.2 +gpg: assuming signed data in 'PrivateBin-1.2.1.tar.gz' +gpg: Signature made Sat Aug 11 22:38:29 2018 CEST +gpg: using RSA key 0xE11B7950E9E183DB +gpg: Good signature from "PrivateBin release (solely used for signing releases)" [] +gpg: aka "PrivateBin code-sign (solely used for code signing) " [] +Primary key fingerprint: 28CA 7C96 4938 EA5C 1481 D42A E11B 7950 E9E1 83DB +``` + +For a more step-by-step guide in detail [see this FAQ](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-can-i-securely-clonedownload-your-project). + +## Reproducible builds + +Since a long time, we signed release `.tar.gz` and `.zip` files with personal PGP keys confirming the authenticity of the fact that the release has been build by a PrivateBin maintainer. + +This uses traditional [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) signatures. + +### How to verify + +Git signature for verifying the reproducibility and that a maintainer in posession with that PGP private key created the release with that content: +``` +$ gpg2 --verify PrivateBin-1.2.1.tar.gz.asc # TODO: update for v1.6.2 +gpg: assuming signed data in 'PrivateBin-1.2.1.tar.gz' +gpg: Signature made Sat Aug 11 22:38:29 2018 CEST +gpg: using RSA key 0xE11B7950E9E183DB +gpg: Good signature from "PrivateBin release (solely used for signing releases)" [] +gpg: aka "PrivateBin code-sign (solely used for code signing) " [] +Primary key fingerprint: 28CA 7C96 4938 EA5C 1481 D42A E11B 7950 E9E1 83DB +``` + +For a more step-by-step guide in detail [see this FAQ](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-can-i-securely-clonedownload-your-project). + +## How to release + +1. Create a release branch (schema: `x.y.z`) and push that as a new branch to GitHub. +2. This will automatically trigger the worflow [/.github/workflows/release.yml](/.github/workflows/release.yml) on GitHub that will generate SLSA provenance _and_ draft a release with most artifacts attached at the end. +3. Now you will need to generate a release `.zip` and `.tar.gz` locally too. Just use `git archive` command for that (TODO: please add specifics). + **Important:** Please don't just download them from GitHub, this bringes no security benefit as that would basically mean trusting GitHub and letting GitHub “build” the release. +4. Sign that release with GPG with your private key: + ``` + git sign # TODO + ``` +5. Upload the `.tar.gz.sig` and `.zip.sig` on GitHub/attach them to the release. + **Note** It may also be a good idea to follow the above guide on how to verify the reproducible builds by verifying the hashes of the two release archives. + Alternatively, you can also compare the hashes of the release file from GitHub and your local one to verify the are the same. From 255fd4b12b1a1e34b3ab1f5adb3a3e980c287dcd Mon Sep 17 00:00:00 2001 From: El RIDO Date: Sat, 16 Dec 2023 07:02:21 +0100 Subject: [PATCH 2/2] updated release document - removed duplicate content - clarified what is signed and since which release - updated verification sample output (also in wiki) using the output of https://github.com/PrivateBin/docker-nginx-fpm-alpine/actions/runs/7228527399/job/19698112056#step:7:156 - Corrected release process - we trigger the release on the push of the tag, not a branch (fixed point in time instead of a moving target) --- doc/Release.md | 62 +++++++++++++++----------------------------------- 1 file changed, 18 insertions(+), 44 deletions(-) diff --git a/doc/Release.md b/doc/Release.md index 97ec02ff..209c4471 100644 --- a/doc/Release.md +++ b/doc/Release.md @@ -1,11 +1,10 @@ # Release -## Properties +## Overview of Supply-Chain Security -### Supply-chain security +As of the PrivateBin 1.0 release we [cryptographically sign](https://git-scm.com/book/uz/v2/Git-Tools-Signing-Your-Work) our git commits and tags, so that you can verify we actually developed the software. Later, we also [started signing the release archives on GitHub](https://github.com/PrivateBin/PrivateBin/issues/219) and retroactively signed all releases from 1.0 forward. -Since [v1.6.2](https://github.com/PrivateBin/PrivateBin/releases/tag/1.6.2) our release assets are [verified with the SLSA framework](https://slsa.dev/). -SLSA stands for „Supply-chain Levels for Software Artifacts”. +Since [release 1.6.2](https://github.com/PrivateBin/PrivateBin/releases/tag/1.6.2) our release assets additionally also are [verified with the SLSA (Supply-chain Levels for Software Artifacts) framework](https://slsa.dev/), providing an in-toto manifest of the release archive. This achieves the following: 1. It ensures no maintainer has gone rogue and has modified/tampered with the source code before “building” the release. @@ -13,58 +12,33 @@ This achieves the following: This includes the workflow file defining how the release is done itself. 3. Our release should achieve [SLSA build level 3](https://slsa.dev/spec/v1.0/levels#build-l3) as it [runs on GitHub](https://slsa.dev/spec/v1.0/threats). Some more properties [are thus achieved](https://slsa.dev/spec/v1.0/threats). -That said, here are some caveasts: -* None of our dependencies has any SLSA verification yet (as of Dec 2023) and thus we (cannot) verify any of our own supply chain. - That said, this is mitigated by the fact that the project has not that many dependencies at all. - For more information [see the corresponding issue](https://github.com/PrivateBin/PrivateBin/issues/1169) and [the GitHub workflow file](/.github/workflows/release.yml). -#### How to verify - -Git signature for verifying the reproducibility and that a maintainer in posession with that PGP private key created the release with that content: -``` -$ gpg2 --verify PrivateBin-1.2.1.tar.gz.asc # TODO: update for v1.6.2 -gpg: assuming signed data in 'PrivateBin-1.2.1.tar.gz' -gpg: Signature made Sat Aug 11 22:38:29 2018 CEST -gpg: using RSA key 0xE11B7950E9E183DB -gpg: Good signature from "PrivateBin release (solely used for signing releases)" [] -gpg: aka "PrivateBin code-sign (solely used for code signing) " [] -Primary key fingerprint: 28CA 7C96 4938 EA5C 1481 D42A E11B 7950 E9E1 83DB -``` - -For a more step-by-step guide in detail [see this FAQ](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-can-i-securely-clonedownload-your-project). - ## Reproducible builds -Since a long time, we signed release `.tar.gz` and `.zip` files with personal PGP keys confirming the authenticity of the fact that the release has been build by a PrivateBin maintainer. +All releases `.tar.gz` and `.zip` archives since 1.0 come with corresponding `.asc` signatures that can be used to confirm the authenticity of the fact that the release has been issued by a PrivateBin maintainer. This uses traditional [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) signatures. -### How to verify +## Verification + +You can use the gpg signatures for verifying the reproducibility and that a maintainer in posession with that PGP private key created the release with that content: -Git signature for verifying the reproducibility and that a maintainer in posession with that PGP private key created the release with that content: ``` -$ gpg2 --verify PrivateBin-1.2.1.tar.gz.asc # TODO: update for v1.6.2 -gpg: assuming signed data in 'PrivateBin-1.2.1.tar.gz' -gpg: Signature made Sat Aug 11 22:38:29 2018 CEST -gpg: using RSA key 0xE11B7950E9E183DB -gpg: Good signature from "PrivateBin release (solely used for signing releases)" [] -gpg: aka "PrivateBin code-sign (solely used for code signing) " [] +$ gpg2 --verify 1.6.2.tar.gz.asc +gpg: assuming signed data in '1.6.2.tar.gz' +gpg: Signature made Fri Dec 15 06:21:08 2023 UTC +gpg: using RSA key 28CA7C964938EA5C1481D42AE11B7950E9E183DB +gpg: Good signature from "PrivateBin release (solely used for signing releases)" [unknown] +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 28CA 7C96 4938 EA5C 1481 D42A E11B 7950 E9E1 83DB ``` For a more step-by-step guide in detail [see this FAQ](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-can-i-securely-clonedownload-your-project). -## How to release +SLSA verification can be performed using the [SLSA verifier](https://github.com/slsa-framework/slsa-verifier#verification-of-slsa-provenance). -1. Create a release branch (schema: `x.y.z`) and push that as a new branch to GitHub. -2. This will automatically trigger the worflow [/.github/workflows/release.yml](/.github/workflows/release.yml) on GitHub that will generate SLSA provenance _and_ draft a release with most artifacts attached at the end. -3. Now you will need to generate a release `.zip` and `.tar.gz` locally too. Just use `git archive` command for that (TODO: please add specifics). - **Important:** Please don't just download them from GitHub, this bringes no security benefit as that would basically mean trusting GitHub and letting GitHub “build” the release. -4. Sign that release with GPG with your private key: - ``` - git sign # TODO - ``` -5. Upload the `.tar.gz.sig` and `.zip.sig` on GitHub/attach them to the release. - **Note** It may also be a good idea to follow the above guide on how to verify the reproducible builds by verifying the hashes of the two release archives. - Alternatively, you can also compare the hashes of the release file from GitHub and your local one to verify the are the same. +## Release process + +The release process is outlined in the [release checklist](https://github.com/PrivateBin/PrivateBin/wiki/Release-Checklist). The key manual steps are performed using a [Makefile](https://github.com/PrivateBin/PrivateBin/blob/master/Makefile#L31-L43) and using a [shell script](https://github.com/rugk/gittools/blob/master/signrelease.sh).