From 43d162f452223f4fecf4c6ea251a1e2e4feda172 Mon Sep 17 00:00:00 2001 From: rugk Date: Fri, 15 Dec 2023 14:17:51 +0100 Subject: [PATCH] =?UTF-8?q?Created=20doc=20for=20=E2=80=9Chow=20to=20verif?= =?UTF-8?q?y=20and=20how=20to=20do=20release=E2=80=9D=20(release=20doc)=20?= =?UTF-8?q?(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.