You clone a Git repository, then pull from it. How can you tell its
contents are “authentic”—i.e., coming from the “genuine” project you
think you’re pulling from, written by the fine human beings you’ve been
working with? With commit signatures and “verified” badges ✅
flourishing, you’d think this has long been solved—but nope!
Four years after Guix deployed its own
tool to allow
users to authenticate updates fetched with guix pull (which uses Git
under the hood), the situation hasn’t changed all that much: the vast
majority of developers using Git simply do not authenticate the code
they pull. That’s pretty bad. It’s the modern-day equivalent of
sharing unsigned tarballs and packages like we’d blissfully do in the
past century.
The authentication mechanism Guix uses for
channels
is available to any Git user through the guix git authenticate
command. This post is a guide for Git users who are not necessarily
Guix users but are interested in using this command for their own
repositories. Before looking into the command-line interface and how we
improved it to make it more convenient, let’s dispel any
misunderstandings or misconceptions.
Why you should care
When you run git pull, you’re fetching a bunch of commits from a
server. If it’s over HTTPS, you’re authenticating the server itself,
which is nice, but that does not tell you who the code actually comes
from—the server might be compromised and an attacker pushed code to the
repository. Not helpful. At all.
But hey, maybe you think you’re good because everyone on your project is
signing commits and tags, and because you’re disciplined, you routinely
run git log --show-signature and check those “Good signature” GPG
messages. Maybe you even have those fancy “✅ verified” badges as found
on
GitLab
and on
GitHub.
Signing commits is part of the solution, but it’s not enough to
authenticate a set of commits that you pull; all it shows is that,
well, those commits are signed. Badges aren’t much better: the presence
of a “verified” badge only shows that the commit is signed by the
OpenPGP key currently registered for the corresponding GitLab/GitHub
account. It’s another source of lock-in and makes the hosting platform
a trusted third-party. Worse, there’s no notion of authorization (which
keys are authorized), let alone tracking of the history of authorization
changes (which keys were authorized at the time a given commit was
made). Not helpful either.
Being able to ensure that when you run git pull, you’re getting code
that genuinely comes from authorized developers of the project is
basic security hygiene. Obviously it cannot protect against efforts to
infiltrate a project to eventually get commit access and insert
malicious code—the kind of multi-year plot that led to the xz
backdoor—but if you don’t even
protect against unauthorized commits, then all bets are off.
Authentication is something we naturally expect from apt update,
pip, guix pull, and similar tools; why not treat git pull to the
same standard?
Initial setup
The guix git authenticate
command authenticates Git checkouts, unsurprisingly. It’s currently
part of Guix because that’s where it was brought to life, but it can be
used on any Git repository. This section focuses on how to use it; you
can learn about the motivation, its design, and its implementation in
the 2020 blog
post, in the 2022
peer-reviewed academic paper entitled Building a Secure Software
Supply Chain with
GNU Guix,
or in this 20mn
presentation.
To support authentication of your repository with guix git authenticate, you need to follow these steps:
-
Enable commit signing on your repo: git config commit.gpgSign true. (Git now supports other signing methods but here we need
OpenPGP signatures.)
-
Create a keyring branch containing all the OpenPGP keys of all
the committers, along these lines:
git checkout --orphan keyring
git reset --hard
gpg --export alice@example.org > alice.key
gpg --export bob@example.org > bob.key
…
git add *.key
git commit -m "Add committer keys."
All the files must end in .key. You must never remove keys from
that branch: keys of users who left the project are necessary to
authenticate past commits.
-
Back to the main branch, add a .guix-authorizations file, listing
the OpenPGP keys of authorized committers—we’ll get back to its
format below.
-
Commit! This becomes the introductory commit from which
authentication can proceed. The introduction of your repository
is the ID of this commit and the OpenPGP fingerprint of the key
used to sign it.
That’s it. From now on, anyone who clones the repository can
authenticate it. The first time, run:
guix git authenticate COMMIT SIGNER
… where COMMIT is the commit ID of the introductory commit, and
SIGNER is the OpenPGP fingerprint of the key used to sign that commit
(make sure to enclose it in double quotes if there are spaces!). As a
repo maintainer, you must advertise this introductory commit ID and
fingerprint on a web page or in a README file so others know what to
pass to guix git authenticate.
The commit and signer are now recorded on the first run in
.git/config; next time, you can run it without any arguments:
guix git authenticate
The other new feature is that the first time you run it, the command
installs pre-push and pre-merge hooks (unless preexisting hooks are
found) such that your repository is automatically authenticated from
there on every time you run git pull or git push.
guix git authenticate exits with a non-zero code and an error message
when it stumbles upon a commit that lacks a signature, that is signed by
a key not in the keyring branch, or that is signed by a key not listed
in .guix-authorizations.
Maintaining the list of authorized committers
The .guix-authorizations file in the repository is central: it lists
the OpenPGP fingerprints of authorized committers. Any commit that is
not signed by a key listed in the .guix-authorizations file of its
parent commit(s) is considered inauthentic—and an error is reported.
The format of
.guix-authorizations
is based on S-expressions
and looks like this:
;; Example ‘.guix-authorizations’ file.
(authorizations
(version 0) ;current file format version
(("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
(name "alice"))
("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
(name "bob"))
("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
(name "charlie"))))
The name bits are hints and do not have any effect; what matters is
the fingerprints that are listed. You can obtain them with GnuPG by
running commands like:
gpg --fingerprint charlie@example.org
At any time you can add or remove keys from .guix-authorizations and
commit the changes; those changes take effect for child commits. For
example, if we add Billie’s fingerprint to the file in commit A, then
Billie becomes an authorized committer in descendants of commit A
(we must make sure to add Billie’s key as a file in the keyring
branch, too, as we saw above); Billie is still unauthorized in branches
that lack A. If we remove Charlie’s key from the file in commit B,
then Charlie is no longer an authorized committer, except in branches
that start before B. This should feel rather natural.
That’s pretty much all you need to know to get started! Check the
manual
for more info.
All the information needed to authenticate the repository is contained
in the repository itself—it does not depend on a forge or key server.
That’s a good property to allow anyone to authenticate it, to ensure
determinism and transparency, and to avoid lock-in.
Interested? You can help!
guix git authenticate is a great tool that you can start using today
so you and fellow co-workers can be sure you’re getting the right code!
It solves an important problem that, to my knowledge, hasn’t really been
addressed by any other tool.
Maybe you’re interested but don’t feel like installing Guix “just” for
this tool. Maybe you’re not into Scheme and Lisp and would rather use a
tool written in your favorite language. Or maybe you think—and
rightfully so—that such a tool ought to be part of Git proper.
That’s OK, we can talk! We’re open to discussing with folks who’d like
to come up with alternative implementations—check out the articles
mentioned above if you’d like to take that route. And we’re open to
contributing to a standardization effort. Let’s get in
touch!
Acknowledgments
Thanks to Florian Pelz and Simon Tournier for their insightful comments
on an earlier draft of this post.
