Skip to content

Commit bcd7435

Browse files
Add CI-aware release signing and cosign verification docs (gopasspw#3431)
Signed-off-by: Dominik Schulz <dominik.schulz@gauner.org>
1 parent fddf2d1 commit bcd7435

4 files changed

Lines changed: 68 additions & 12 deletions

File tree

‎.github/workflows/autorelease.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ on:
1111

1212
permissions:
1313
contents: read
14+
id-token: write
1415

1516
jobs:
1617
goreleaser:

‎.goreleaser.yml‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ builds:
3939
goarm:
4040
- 6
4141
- 7
42+
ignore:
43+
- goos: windows
44+
goarch: arm
4245
mod_timestamp: '{{ .CommitTimestamp }}'
4346
archives:
4447
- id: gopass
@@ -156,9 +159,40 @@ milestones:
156159

157160
signs:
158161
-
159-
id: gopass
162+
id: gopass-gpg
163+
cmd: sh
164+
artifacts: checksum
165+
env:
166+
- "ARTIFACT=${artifact}"
167+
- "SIGNATURE=${signature}"
168+
args:
169+
- -ec
170+
- |
171+
if [ -n "${GPG_FINGERPRINT:-}" ]; then
172+
exec gpg --batch -u "${GPG_FINGERPRINT}" --armor --output "${SIGNATURE}" --detach-sign "${ARTIFACT}"
173+
fi
174+
175+
echo "skipping GPG signing; set GPG_FINGERPRINT to sign locally" >&2
176+
-
177+
id: gopass-cosign
178+
cmd: sh
160179
artifacts: checksum
161-
args: ["--batch", "-u", "{{ .Env.GPG_FINGERPRINT }}", "--armor", "--output", "${signature}", "--detach-sign", "${artifact}"]
180+
signature: "${artifact}.sigstore.json"
181+
env:
182+
- "ARTIFACT=${artifact}"
183+
- "SIGNATURE=${signature}"
184+
args:
185+
- -ec
186+
- |
187+
if [ "${GITHUB_ACTIONS}" = "true" ]; then
188+
exec cosign sign-blob --bundle="${SIGNATURE}" "${ARTIFACT}" --yes
189+
fi
190+
191+
if [ -n "${COSIGN_KEY:-}" ]; then
192+
exec cosign sign-blob --key "${COSIGN_KEY}" --bundle="${SIGNATURE}" "${ARTIFACT}" --yes
193+
fi
194+
195+
echo "skipping cosign signing outside GitHub Actions; set COSIGN_KEY to sign locally" >&2
162196
163197
# creates SBOMs of all archives and the source tarball using syft
164198
# https://goreleaser.com/customization/sbom

‎docs/releases.md‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Releases
1+
# Releases
22

33
Note: Only members who have at least `write` [access](https://github.com/gopasspw/gopass/settings/access) to the gopass repo can create releases.
44

@@ -10,7 +10,7 @@ Note: We use semantic versioning for the command line interface and tool behavio
1010
but not for the API (i.e. `pkg/gopass`). Maintaining both properties in the
1111
same repository / Go module is too cumbersome.
1212

13-
### Development overview
13+
## Development overview
1414

1515
Preparing and creating a new release requires a number of steps.
1616
Starting right after the previous release these are roughly:
@@ -23,7 +23,7 @@ Starting right after the previous release these are roughly:
2323
* This usually either happens in Slack or on semi-regular video calls
2424
* After all blockers have been addressed we move the remaining issues to the next milestone and prepare the release
2525

26-
### Cutting a release
26+
## Cutting a release
2727

2828
This section is a reference for contributors with write access to the gopass
2929
repository.
@@ -73,6 +73,21 @@ Afterwards a maintainer should run the post-release automation that will
7373
perform some cleanup, create new GitHub milestones and send out PRs to
7474
rolling release distributions.
7575

76+
### Verifying published assets
77+
78+
Release automation publishes `SHA256SUMS` together with a keyless cosign bundle
79+
named `SHA256SUMS.sigstore.json`. After downloading both assets from a GitHub
80+
release, verify them with:
81+
82+
```bash
83+
cosign verify-blob \
84+
--bundle SHA256SUMS.sigstore.json \
85+
SHA256SUMS
86+
```
87+
88+
Once the checksum file is verified, use it to validate the archive or package
89+
you downloaded with your usual checksum tooling.
90+
7691
### Releasing a cherry-pick release
7792

7893
This subsection applies to a new release that should be based on a previous
@@ -90,14 +105,14 @@ This can still use our release automation but it will require some adjustments:
90105
* Push the release branch printed at the end to the repository (or your fork) and open a PR.
91106
* IMPORANT: This PR will not be merged into master! We will just use it to create a tag and trigger the release automation.
92107

93-
### Reproducible Builds
108+
## Reproducible Builds
94109

95110
`gopass` supports [reproducible builds](https://reproducible-builds.org/). When
96111
building from git [`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/docs/source-date-epoch/)
97112
can be used to override the compile date, .e.g `SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)`.
98113
When building a release `goreleaser` will automatically use the exact timestamp
99114
of the last commit.
100115

101-
Internal paths are stripped using `-trimpath` and appropriate `-ldflags` (e.g.
116+
Internal paths are stripped using `-trimpath` and appropriate `-ldflags` (e.g.
102117
`-s`, `-w`). See the Makefile header for the exact set of flags.
103118

‎internal/updater/README.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,20 @@ The configuration for those is spread across the repository and the GitHub Actio
2626
A new release is published by pushing a version tag (`v*`) to the repository. Once that happens the GHA workflow `autorelease.yml` is kicked off. It is configured in `.github/workflows/autorelease.yml` and through a number of injected environment variables from the GHA settings. Most importantly `GPG_PRIVATE_KEY` which contains the armored
2727
GPG private part of the current release signing key and the respective passphrase in `PASSPHRASE`.
2828

29-
GoReleaser is controlled by `.goreleaser.yml` in the root of this repository. The relevant sections there are `checksum` to ensure a checksum file is generated and the `signs` section to sign the checksum file using the provided `GPG_FINGERPRINT` in the workflow.
29+
GoReleaser is controlled by `.goreleaser.yml` in the root of this repository. The relevant sections there are `checksum` to ensure a checksum file is generated and the `signs` section to sign the checksum file. We currently publish both a GPG signature for the updater (`SHA256SUMS.sig`) and a keyless cosign bundle (`SHA256SUMS.sigstore.json`) for external verification.
30+
31+
For maintainers running local snapshot releases: signing is skipped unless the
32+
required release credentials are available. Set `GPG_FINGERPRINT` to produce the
33+
GPG checksum signature locally, and set `COSIGN_KEY` to produce a local cosign
34+
bundle. Keyless cosign signing only runs in GitHub Actions where OIDC identity
35+
is available.
3036

3137
## Managing keys and related assets
3238

3339
The relase signing key is set to expire every other year, so we need to follow a certain key rotation protocol to allow for a seamless key rotation.
3440

3541
* At T-6 Month we should notice that `TestGPGVerifyIn6Months` starts to fail.
36-
* There is likely a loss obstrusive way to achieve that, but I'll leave it at that for now.
42+
* There is likely a loss obstrusive way to achieve that, but I'll leave it at that for now.
3743
* We should then create an issue to track the key rollover (this should never happen in secret). The entire security posture isn't perfect but that's the best I can do with my resources. Help always appreciated.
3844
* For the actual rollout we first need to generate a new key. That needs to be done by exactly one core maintainer with write access to the repo and the GHA secrets since only they can inject the new key, fingerprint and passphrase.
3945
* To generate the key run: `gpg --expert --full-generate-key` and select `RSA and RSA`, `3072` (bits) and a validity of `2y`. Use `Gopass Release Signing Key YYYY` as the name, `GitHub Actions only` as the comment and `release@gopass.pw` as the email.
@@ -52,9 +58,9 @@ The relase signing key is set to expire every other year, so we need to follow a
5258
* Create a file that contains `gopass-sign-test\n` and run `gpg -u 0xKEYID --armor --output /tmp/testdata.sig --detatch-sign testdata`. Use the correct KEYID (the one of the NEW key).
5359
* Hint: Make sure the input only contains one line break, not two.
5460
* Paste the content of /tmp/testdata.sig into the `testSignature` in `verify_test.go`. Make sure all tests pass.
55-
* Navigate to https://github.com/gopasspw/gopass/settings/secrets/actions
56-
* Paste the armored private part of the new key into the existing `GPG_PRIVATE_KEY` secret.
57-
* Paste the corresponding passphrase into `PASSPHRASE`.
61+
* Navigate to <https://github.com/gopasspw/gopass/settings/secrets/actions>
62+
* Paste the armored private part of the new key into the existing `GPG_PRIVATE_KEY` secret.
63+
* Paste the corresponding passphrase into `PASSPHRASE`.
5864
* At this point you should be able to safely delete the old public key from verify.go and kick off a new release.
5965
* At the very end upload the new key to some keyservers: `gpg --send-keys 0xKEYID` and possibly `gpg --keyserver pgp.mit.edu --send-keys 0xKEYID`.
6066
* In case you mess up during key generation you might need to start over and you don't want to have conflicting keys on a keyserver where you can't delete them.

0 commit comments

Comments
 (0)
⌂ 换网址