title: Hosting signify signatures on cgit
date: 2021-05-16
author: Wolfgang Müller
A seemingly overlooked[^1] feature of [cgit](https://git.zx2c4.com/cgit/about/)
is its ability to host detached signatures of the snapshots it generates. Add a
signature of a snapshot to the Git repository, and cgit will automatically
offer it right next to the corresponding snapshot:
<figure>
<img class="round" src="img/cgit-signatures.png" width="60%" alt="Detached signatures
linked alongside compressed tarballs"/>
<figcaption>Detached signatures in their natural habitat</figcaption>
</figure>
But how does cgit know which signature corresponds to which snapshot, and how
are signatures stored in the Git repository itself? Enter
[`git-notes(1)`](https://git-scm.com/docs/git-notes), another feature that is
probably overlooked. Intended to facilitate adding additional notes to commit
messages without changing the commit itself, `git-notes(1)` lends itself well to
attaching textual data to any Git object such as a commit or a tag.
## Duly noted
Internally, Git stores the contents of a note as a
[blob](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects), meaning it is
saved to the object database and referred to by its hash. But Git must also
store which commit a note belongs to. For this it uses a
[tree](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#_tree_objects).
A tree is Git's way of encoding a directory: it contains a list of paths, and
maps them to blobs (files) or other trees (subdirectories). We can look at those
trees using [`git-cat-file(1)`](https://git-scm.com/docs/git-cat-file). For
example, the following is the tree for [this
commit](https://git.oriole.systems/quarg/commit/?id=7cd07362c4c13bfd01afa85a4666c491a020f330):
```
$ git cat-file -p 6a81213f2e88a33835f2fb94015bda5dc04a397c
100644 blob 3feb78adc667d7bf4ad2cec4fb780b29ced25302 .gitignore
100644 blob 2149bd82c51e65c34d8aee87f96c4f1c1af8f6c1 LICENSE
100644 blob d397eaf5a75d0d30c4d9d2ffcd1007b44acc842a quarg.1
040000 tree eee3c892c769bad3b7d883f0a162500406f67c3b quarg
100644 blob 1a861ec51a39cbefa0f5027995c358af2224ebbb setup.py
```
The tree object that links notes, however, uses the commit blob itself as a
"path". In the following tree (for
[this](https://git.oriole.systems/quarg/commit/?h=refs/notes/signatures/tar.gz&id=f12709c0843a89b5be37fe499b9928a8c11cbcd9)
commit) the note blob is on the left side whilst the commit blob ("path") is on
the right:
```
$ git cat-file -p 3a5fd837cae7e478b9a230f6c301c93efda7c1e2
100644 blob 5c7ec832f83342aa460bb27b0b75e12695a98a53 43c9fb13e063cebfd08e741b67b9ec2317aed4b9
```
Let's see which commit that is:
```
$ git show -s --pretty=oneline 43c9fb13e063cebfd08e741b67b9ec2317aed4b9
43c9fb13e063cebfd08e741b67b9ec2317aed4b9 (tag: 0.1.2) Prepare for release of 0.1.2
```
The note tree is then linked in a normal [commit
object](https://git.oriole.systems/quarg/commit/?h=refs/notes/signatures/tar.gz&id=f12709c0843a89b5be37fe499b9928a8c11cbcd9)
that a special
[ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) points to. By
default, that is `refs/notes/commits`. One may think of that ref as pointing to
a special branch holding all the information on notes "published" to that
branch.
Instead of that default location, cgit looks in `refs/notes/signatures/<format>`
for any signatures. For example, signatures for a gzip-compressed tarball are
stored in `refs/notes/signatures/tar.gz`. If cgit finds a signature attached to
a tag and can generate a matching tarball, it will automatically link the
contents of the note blob as a `.asc`[^2] file.
## Snap, shot!
With the Git internals out of the way, let's break down the process of hosting a
signature on cgit.
Before we get to the actual signing process, a quick but important detour. Since
we will be publishing signatures of the snapshot itself, we have to make sure
that its contents are stable. Furthermore, we have to be absolutely certain that
cgit is generating the same snapshot that we used when we made the signature.
We could of course tag a release, download the snapshot via cgit ourselves,
verify that it contains the correct files, and then sign it, but that seems
backwards; we just blindly trusted the cgit machinery to give us what we expect.
What if our cgit host had been compromised? We should make sure that we can
create the same snapshot locally.
Thankfully, this is a trivial thing to do. We can use
[`git-archive(1)`](https://git-scm.com/docs/git-archive) to create a stable
archive[^3] from any tag. This is, in fact, also what cgit does internally. By
default, `git-archive(1)` does not prefix the files in the archive with the
project title and tag, so to make sure that we get a sane[^4] tarball, we have to
pass the right prefix -- just as cgit does:
```
$ git archive --prefix=quarg-0.1.2/ -o quarg-0.1.2.tar.gz -- 0.1.2
```
The resulting file should be exactly what you get when you download a snapshot
for the same version from cgit.
## Signed, Sealed, Delivered
Now that we have the actual snapshot, we can get to signing it.
The example in `cgitrc(5)` uses the dreaded `gpg(1)` interface to generate a
signature, but since notes are just textual objects, we can use any utility that
generates a signature in text form. I will be using OpenBSD's
[signify](https://www.openbsd.org/papers/bsdcan-signify.html), a tool I have
been recommending for a long time given its simplicity and ease of use[^5].
To make things more straightforward and give people who do not want to use
signify a way of verifying the integrity of the download, we do not sign the
snapshot itself, but its checksum. Conveniently, signify supports verifying the
signature and checksum in one invocation[^6].
Since signify expects BSD-style checksums from OpenBSD's
[`sha256(1)`](https://man.openbsd.org/sha256), we have to make sure to pass the
`--tag` option to its GNU counterpart,
[`sha256sum(1)`](https://manpages.debian.org/buster/coreutils/sha256sum.1.en.html):
```
$ sha256sum --tag quarg-0.1.2.tar.gz > quarg-0.1.2.tar.gz.SHA256
```
Finally, the following invocation of signify cryptographically signs the
checksum file using our secret key and writes the signature to
`quarg-0.1.2.tar.gz.SHA256.sig`:
```
$ signify -Ses release.sec -m quarg-0.1.2.tar.gz.SHA256
```
## Final assembly
Now all that is left is to store the signature in Git's object database using
[`git-hash-object(1)`](https://git-scm.com/docs/git-hash-object) and tell
`git-notes(1)` to link that blob to the `0.1.2` release tag:
```
$ git notes --ref=signatures/tar.gz add -C "$(git hash-object -w quarg-0.1.2.tar.gz.SHA256.sig)" 0.1.2
```
Let's take a look at the signature we just stored:
```
$ git notes --ref=signatures/tar.gz show 0.1.2
untrusted comment: verify with release.pub
RWRyR8jRAxhmZ8C5e7Vxkaed4Tg5Po+Qg4J+0LvjfRRfzch1MqUL8nzkrtGEB8fLG1+DwRYkzYdcZ7qjcYSPx048lTSVpqjSAAc=
SHA256 (quarg-0.1.2.tar.gz) = 1b6610c2417f36b5b1df5208c3c641b8b2ac3283dae87f453801cdc8c4ffb80a
```
Looks good. Let's verify it before publishing:
```
$ git notes --ref=signatures/tar.gz show 0.1.2 | signify -Cp release.pub -x -
Signature Verified
quarg-0.1.2.tar.gz: OK
```
Great, this is ready to be published. Git will not include `refs/notes/*` by
default when pushing, so to update the upstream repository with the new
signatures, we have to push the ref manually:
```
$ git push origin refs/notes/signatures/tar.gz
```
Similarly, a regular clone of the repository will not download any note objects
by default. If you want to have a look at the signatures for
[weltschmerz](https://git.oriole.systems/weltschmerz/) or
[quarg](https://git.oriole.systems/quarg/), for example, you have to fetch them
manually like so:
```
$ git fetch origin refs/notes/signatures/tar.gz:refs/notes/signatures/tar.gz
```
Git also supports showing notes in
[`git-log(1)`](https://git-scm.com/docs/git-log) directly, by use of the
`--notes` option. The following will display any signatures for the tar.gz
format inline after the commit message[^7]:
```
$ git log --notes=signatures/tar.gz
```
## When in doubt, automate
Of course doing all of this every time one wants to carve a new release is a bit
tedious, so I ended up writing a [small helper script](https://git.oriole.systems/git-helpers/tree/git-sign-for-cgit).
For now it hardcodes the invocation of signify, but it should be easily
extensible to accommodate other tools.
[^1]: It is mentioned briefly in [`cgitrc(5)`](https://git.zx2c4.com/cgit/tree/cgitrc.5.txt?id=892ba8c3cc0617d2087a2337d8c6e71524d7b49c#n777)
but I have yet to see it be deployed widely. Of course it might also be that
signatures are not valued that much anymore these days.
[^2]: Whilst I'd prefer `.sig` for signify signatures specifically, this would
need patching in cgit. So for now I have to concede and accept that Firefox
calls it a 'detached OpenPGP signature' even though it isn't.
[^3]: An interesting side effect that I only
[recently](https://git.oriole.systems/site/commit/?id=0da8a6e3d85a98e38b1abc2499f7e7b3fe5d9534)
noticed is that by signing tarballs generated by `git-archive(1)` one also
implicitly signs a commit. Read more
[here](https://oriole.systems/posts/verify-with-signify#Verification%20of%20the%20corresponding%20commit).
[^4]: The worst sin a tarball can commit is having all files saved at toplevel,
polluting the directory it is extracted into.
[^5]: A portable version is available
[here](https://github.com/aperezdc/signify).
[^6]: This is so that you can verify a whole set of files with just one
signature.
[^7]: Note that we do not have to type out the full ref here. `git-log(1)`
will make sure to [form the full name](https://git-scm.com/docs/git-log#Documentation/git-log.txt---notesltrefgt).
`git-notes` also supports these short forms.
