blitzwing/bintzwing
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

updated release document

Browse source 
- 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)
This commit is contained in:
El RIDO 2023-12-16 07:02:21 +01:00
parent 43d162f452
commit 255fd4b12b
1 changed files with 18 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
doc/Release.md
View file

@ -1,11 +1,10 @@
# Release # 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/). 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.
SLSA stands for „Supply-chain Levels for Software Artifacts”.
This achieves the following: This achieves the following:
1. It ensures no maintainer has gone rogue and has modified/tampered with the source code before “building” the release. 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. 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). 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). 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)" [<trust level here>]
gpg: aka "PrivateBin code-sign (solely used for code signing) <git@privatebin.net>" [<trust level here>]
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 ## 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. 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 $ gpg2 --verify 1.6.2.tar.gz.asc
gpg: assuming signed data in 'PrivateBin-1.2.1.tar.gz' gpg: assuming signed data in '1.6.2.tar.gz'
gpg: Signature made Sat Aug 11 22:38:29 2018 CEST gpg: Signature made Fri Dec 15 06:21:08 2023 UTC
gpg: using RSA key 0xE11B7950E9E183DB gpg: using RSA key 28CA7C964938EA5C1481D42AE11B7950E9E183DB
gpg: Good signature from "PrivateBin release (solely used for signing releases)" [<trust level here>] gpg: Good signature from "PrivateBin release (solely used for signing releases)" [unknown]
gpg: aka "PrivateBin code-sign (solely used for code signing) <git@privatebin.net>" [<trust level here>] 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 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). 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. ## Release process
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). 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).
**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.