[bug#70759] [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[bug#70759] [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[Ludovic Courtès]

* website/posts/git-authenticate.md: New file.
---
 website/posts/git-authenticate.md | 217 ++++++++++++++++++++++++++++++
 1 file changed, 217 insertions(+)
 create mode 100644 website/posts/git-authenticate.md

Hello Guix!

In my quest to make the world a better place *cough* I thought I’d
take the recent improvements to ‘guix git authenticate’¹ as an
opportunity to spread the word about Git checkout authentication,
about the tool, and to send a call for action—I’d love to see
someone implement it or a variant thereof for a broader audience.

I’d like to publish this blog post in the coming days.

Feedback welcome!

Thanks,
Ludo’.

¹ https://issues.guix.gnu.org/69780

diff --git a/website/posts/git-authenticate.md b/website/posts/git-authenticate.md
new file mode 100644
index 0000000..9950b37
--- /dev/null
+++ b/website/posts/git-authenticate.md
@@ -0,0 +1,217 @@
+title: Authenticate your Git checkouts!
+author: Ludovic Courtès
+tags: Security, Software development
+date: 2024-05-06 14:14
+---
+
+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](https://guix.gnu.org/en/blog/2020/securing-updates/) 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](https://guix.gnu.org/manual/devel/en/html_node/Channels.html)
+is available to any Git user through the [`guix git
+authenticate`](https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-git-authenticate.html)
+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](https://docs.gitlab.com/ee/user/project/repository/signed_commits/gpg.html)
+and [on
+GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification).
+
+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.  If you register a new key, or if you leave the project, your
+commits lose their badge.  Not helpful either, not to mention that this
+is all tied to the hosting site you’re on, outside of Git’s control.
+
+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](https://tukaani.org/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`](https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-git-authenticate.html)
+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](https://guix.gnu.org/en/blog/2020/securing-updates/), in the 2022
+peer-reviewed academic paper entitled [_Building a Secure Software
+Supply Chain with
+GNU Guix_](https://doi.org/10.22152/programming-journal.org/2023/7/1),
+or in this 20mn
+[presentation](https://archive.fosdem.org/2023/schedule/event/security_where_does_that_code_come_from/).
+
+To support authentication of your repository with `guix git
+authenticate`, you need to follow these steps:
+
+  0. Enable commit signing on your repo: `git config commit.gpgSign
+	 true`.  (Git now supports other signing methods but here we need
+	 OpenPGP signatures.)
+
+  1. 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
+	 …
+	 git add *.key
+	 git commit -a -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.
+
+  2. 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.
+
+  3. 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`](https://guix.gnu.org/manual/devel/en/html_node/Specifying-Channel-Authorizations.html#channel_002dauthorizations)
+is based on [S-expressions](https://en.wikipedia.org/wiki/S-expression)
+and looks like this:
+
+```scheme
+;; 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](https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-git-authenticate.html)
+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](https://guix.gnu.org/contact/)!

base-commit: a4153e25c8fc37920a56330a60734f4205f3dcb0
-- 
2.41.0

[bug#70759] [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[pelzflorian (Florian Pelz)]

Hi Ludo and thank you for the tool and this presentation of it!

It is all well-written.  I only notice that there are typewriter
apostrophes like “you've” mixed with typographic apostrophes “you’d”.

Ludovic Courtès <ludo@gnu.org> writes:
> +# Why you should care

It is good how this lists all the concepts that are insufficient. :)
I think the explanations suffice.

However I hesitate here:

> +	 ```
> +	 git checkout --orphan keyring
> +	 git reset --hard
> +	 gpg --export alice@example.org > alice.key
> +	 …
> +	 git add *.key
> +	 git commit -a -m "Add committer keys."

Why the -a?

Regards,
Florian

[bug#70759] [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[Ludovic Courtès]

Hi Florian,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

> It is all well-written.  I only notice that there are typewriter
> apostrophes like “you've” mixed with typographic apostrophes “you’d”.

Oops!  Fixed locally.

> Ludovic Courtès <ludo@gnu.org> writes:
>> +# Why you should care
>
> It is good how this lists all the concepts that are insufficient. :)
> I think the explanations suffice.

Great, I’m glad it makes sense.  There seems to be a common perception
that “there’s no problem” so if this section manages to dispel that
myth, that’s good.

> However I hesitate here:
>
>> +	 ```
>> +	 git checkout --orphan keyring
>> +	 git reset --hard
>> +	 gpg --export alice@example.org > alice.key
>> +	 …
>> +	 git add *.key
>> +	 git commit -a -m "Add committer keys."
>
> Why the -a?

Oh you’re right, it’s unnecessary.  Removed!

Thanks for the quick feedback!

Ludo’.

[bug#70759] [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[Simon Tournier]

Hi Ludo,

On ven., 03 mai 2024 at 22:57, Ludovic Courtès <ludo@gnu.org> wrote:

> +# Why you should care

[...]

>                                   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.  If you register a new key, or if you leave the project, your
> +commits lose their badge.  Not helpful either, not to mention that this
> +is all tied to the hosting site you’re on, outside of Git’s control.

Well, there is a double-sword here, IMHO.  Because considering the
“keyring” branch approach, it reads: « keys of users who left the
project are necessary to authenticate past commits. »

Therefore, I do not see the problem with badges if you apply the same
constraint: do not remove the keys.  Somehow, I would mitigate this
paragraph.

Other said, the main (and maybe only one) cons against badges is that
the (meta)information does not belong to the Git repository itself but
is registered somewhere in the platform^W service.  And that breaks the
decentralized “claim“, i.e., it forces developer to login in such
services; it locks all contributors in one service.

Somehow, the “keyring” branch approach is about software and “badges” is
about service.  It’s easy to have the control on the former and it’s
much harder to control the latter.


> +# Initial setup

[...]

> +That’s it.  From now on, anyone who clones the repository can
> +authenticate it.  The first time, run:
> +
> +```
> +guix git authenticate COMMIT SIGNER
> +```

This command does not require much Guix, right?  Since the aim of this
post is to convince non-Guix, I would try to extract the Guile code and
have something without the call of “guix”.

If there is a Guile script, named ’git-authenticate’, then any user
putting this script somewhere in PATH would have it.  They would just
run:

   git authenticate COMMIT SIGNER

then it does all the dance. :-)

For sure, there is a maintenance issue; duplicate code, etc.  However,
the call-product would be this autonomous Guile script, infrequently
updated – displaying a HUGE warning and asking to rely on “guix git
authenticate” instead.

I think this strategy would be better if the aim is to reach non-Guix
people. :-)


> +# 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.

Hum, I am doing a big cup of coffee, starting loud music in my
headphones and I would do right now what I am proposing above. :-)

Could you wait one or two days before publishing?  I think it could be
nice to come with a Guile script so let me copy/paste some code around.
If there is no news from me, it means: more work than my
constraints. :-)

Cheers,
simon

[bug#70759] [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[Ludovic Courtès]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> skribis:

> On ven., 03 mai 2024 at 22:57, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> +# Why you should care
>
> [...]
>
>>                                   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.  If you register a new key, or if you leave the project, your
>> +commits lose their badge.  Not helpful either, not to mention that this
>> +is all tied to the hosting site you’re on, outside of Git’s control.
>
> Well, there is a double-sword here, IMHO.  Because considering the
> “keyring” branch approach, it reads: « keys of users who left the
> project are necessary to authenticate past commits. »
>
> Therefore, I do not see the problem with badges if you apply the same
> constraint: do not remove the keys.  Somehow, I would mitigate this
> paragraph.

If you do not see the problem with badges, then this paragraph might
need to be revisited!

> Other said, the main (and maybe only one) cons against badges is that
> the (meta)information does not belong to the Git repository itself but
> is registered somewhere in the platform^W service.  And that breaks the
> decentralized “claim“, i.e., it forces developer to login in such
> services; it locks all contributors in one service.
>
> Somehow, the “keyring” branch approach is about software and “badges” is
> about service.  It’s easy to have the control on the former and it’s
> much harder to control the latter.

Thanks for explaining.

I tried to reword it in a way similar to what I did in the Programming
paper to clarify that it’s not just about lock-in but also about
semantics:

  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.  Not helpful.

Does that clarify things?

>> +That’s it.  From now on, anyone who clones the repository can
>> +authenticate it.  The first time, run:
>> +
>> +```
>> +guix git authenticate COMMIT SIGNER
>> +```
>
> This command does not require much Guix, right?

Technically it requires quite a bit.

> Since the aim of this post is to convince non-Guix, I would try to
> extract the Guile code and have something without the call of “guix”.

As I see it, the aim of the post is to invite interested parties to
either extract the relevant Guile code from Guix (this is quite a bit of
work and there are technico-social issues to solve) or to write their
own.

I did not intend to do that work before publishing the post; quite the
opposite.

I hope that clarifies my intention.

>> +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.
>
> Hum, I am doing a big cup of coffee, starting loud music in my
> headphones and I would do right now what I am proposing above. :-)
>
> Could you wait one or two days before publishing?  I think it could be
> nice to come with a Guile script so let me copy/paste some code around.
> If there is no news from me, it means: more work than my
> constraints. :-)

Yes well, I don’t think we should hold on until the work has been done;
like I wrote, that’s precisely the purpose of this post.

Now, if you get it done, you have my recognition *and* we can post a
followup saying: look, there’s now at least one standalone tool for you.
:-)

Thanks,
Ludo’.

[bug#70759] [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[Simon Tournier]

Hi,

On Mon, 6 May 2024 at 17:49, Ludovic Courtès <ludo@gnu.org> wrote:

> I tried to reword it in a way similar to what I did in the Programming
> paper to clarify that it’s not just about lock-in but also about
> semantics:
>
>   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.  Not helpful.
>
> Does that clarify things?

Yes, this wording clarifies the issue of badges.  For what my view is
worth here, I would write: badges acts as a service, as with an
infrastructure as a service or platform as a service.  Else LGTM.


> I hope that clarifies my intention.

Thanks for the clarification.

> Now, if you get it done, you have my recognition *and* we can post a
> followup saying: look, there’s now at least one standalone tool for you.
> :-)

Deal. :-)

Cheers,
simon

bug#70759: [PATCH guix-artwork] website: Add post about ‘guix git authenticate’.

[Ludovic Courtès]

Hi,

Simon Tournier <zimon.toutoune@gmail.com> skribis:

> On Mon, 6 May 2024 at 17:49, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> I tried to reword it in a way similar to what I did in the Programming
>> paper to clarify that it’s not just about lock-in but also about
>> semantics:
>>
>>   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.  Not helpful.
>>
>> Does that clarify things?
>
> Yes, this wording clarifies the issue of badges.  For what my view is
> worth here, I would write: badges acts as a service, as with an
> infrastructure as a service or platform as a service.  Else LGTM.

OK, pushed:

  https://guix.gnu.org/en/blog/2024/authenticate-your-git-checkouts/

Thanks for your feedback!

Ludo’.