Signing git tags for releases

Signing git tags for releases

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 974 bytes --]

I would like to suggest that we start signing git tags in our
repository.  This would give greater confidence that a particular commit
is in fact the one corresponding to a particular release (e.g. the one
with some security fix and not an older one).

It is not strictly necessary in the sense that we are okay as-is, but I
think it's good form and a generally accepted best practice.  For
context, see also the previous discussion in Bug#24461.

AFAIK, this will not require any action on behalf of anyone except the
person making our releases, unless they specifically want to verify some
signed git tag with "git tag -v TAG".  In that case, they will obviously
first need to fetch the corresponding public key.

Unless I am overlooking something, the necessary documentation changes
will be in make-tarball.txt only.  See the attached diff.

If there are no objections to this plan, I hope to start doing this
from Emacs 28.0.91 (the second pretest release) and onward.

[-- Attachment #2: sign.diff --]
[-- Type: text/x-diff, Size: 1600 bytes --]

diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index 872cb00ca2..c56c887e19 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -187,7 +187,7 @@ General steps (for each step, check for possible errors):
 8.  You can now tag the release/pretest and push it together with the
     last commit:
 
-     cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
+     cd EMACS_ROOT_DIR && git tag -a -s TAG -m "Emacs TAG"
      git push
      git push --tags
 
@@ -199,16 +199,20 @@ General steps (for each step, check for possible errors):
     use the SHA1 of the last commit which went into the release
     tarball, in case there were some intervening commits since then:
 
-     git tag -a TAG -m "Emacs TAG" SHA1
+     git tag -a -s TAG -m "Emacs TAG" SHA1
      git push --tags
 
     In the past, we were not always consistent with the annotation
     (i.e. -m "Emacs TAG").  The preferred format is like this for a
     pretest, release candidate and final release:
 
-     git tag -a emacs-28.0.90  -m "Emacs 28.0.90 pretest"
-     git tag -a emacs-28.1-rc1 -m "Emacs 28.1 RC1"
-     git tag -a emacs-28.1     -m "Emacs 28.1 release"
+     git tag -a -s emacs-28.0.90  -m "Emacs 28.0.90 pretest"
+     git tag -a -s emacs-28.1-rc1 -m "Emacs 28.1 RC1"
+     git tag -a -s emacs-28.1     -m "Emacs 28.1 release"
+
+    The "-s" option above means to sign the tag using your default GPG
+    key.  Make sure this uses the same GPG key that you use to sign
+    the release (see below).
 
 9. Decide what compression schemes to offer.
     For a release, at least gz and xz:

Re: Signing git tags for releases

[Teemu Likonen]

[-- Attachment #1: Type: text/plain, Size: 1325 bytes --]

* 2021-12-02 16:06:33-0800, Stefan Kangas wrote:

> I would like to suggest that we start signing git tags in our
> repository.

Good idea, at least in general.

> -     cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
> +     cd EMACS_ROOT_DIR && git tag -a -s TAG -m "Emacs TAG"

Don't use "-a" and "-s" together, just use "-s". A quote from git-tag(1)
manual:

       -a, --annotate
           Make an unsigned, annotated tag object

       -s, --sign
           Make a GPG-signed tag, using the default e-mail address’s key.
           The default behavior of tag GPG-signing is controlled by
           tag.gpgSign configuration variable if it exists, or disabled
           otherwise. See git-config(1).

> -     git tag -a TAG -m "Emacs TAG" SHA1
> +     git tag -a -s TAG -m "Emacs TAG" SHA1

> -     git tag -a emacs-28.0.90  -m "Emacs 28.0.90 pretest"
> -     git tag -a emacs-28.1-rc1 -m "Emacs 28.1 RC1"
> -     git tag -a emacs-28.1     -m "Emacs 28.1 release"
> +     git tag -a -s emacs-28.0.90  -m "Emacs 28.0.90 pretest"
> +     git tag -a -s emacs-28.1-rc1 -m "Emacs 28.1 RC1"
> +     git tag -a -s emacs-28.1     -m "Emacs 28.1 release"

The same here.

-- 
/// Teemu Likonen - .-.. https://www.iki.fi/tlikonen/
// OpenPGP: 6965F03973F0D4CA22B9410F0F2CAE0E07608462

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 434 bytes --]

Re: Signing git tags for releases

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> I would like to suggest that we start signing git tags in our
> repository.  This would give greater confidence that a particular commit
> is in fact the one corresponding to a particular release (e.g. the one
> with some security fix and not an older one).

I'm in favour -- I think many (most?) larger projects do it this way
now.  But I have no idea whether there's any drawbacks.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Signing git tags for releases

[Stefan Kangas]

Teemu Likonen <tlikonen@iki.fi> writes:

> Don't use "-a" and "-s" together, just use "-s". A quote from git-tag(1)
> manual:

Good catch, thank you.

Re: Signing git tags for releases

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> I would like to suggest that we start signing git tags in our
>> repository.  This would give greater confidence that a particular commit
>> is in fact the one corresponding to a particular release (e.g. the one
>> with some security fix and not an older one).
>
> I'm in favour -- I think many (most?) larger projects do it this way
> now.  But I have no idea whether there's any drawbacks.

There have been no other comments within a week, besides the one from
Teemu Likonen who spotted a mistake in the patch I proposed.

If anyone has anything more to add here, there is still some time to
speak up before it is time for the second pretest.  If I don't see any
further comments until then, I will go ahead with the proposed plan.

Thanks.

Re: Signing git tags for releases

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 8 Dec 2021 14:06:33 -0800
> Cc: emacs-devel@gnu.org
> 
> There have been no other comments within a week, besides the one from
> Teemu Likonen who spotted a mistake in the patch I proposed.
> 
> If anyone has anything more to add here, there is still some time to
> speak up before it is time for the second pretest.  If I don't see any
> further comments until then, I will go ahead with the proposed plan.

At least one important aspect remains un-discussed: how do we make
sure the keys of those who sign tags are made available for the
others, who'd like to verify the signatures.  This will have to be
described in CONTRIBUTE, with enough detail for people to follow even
if they aren't experts in GnuPG use.

More generally, what exactly is proposed?  I think it would be good to
see some text for CONTRIBUTE and/or make-tarball.txt (or other docs)
with what will be the procedures related to this.

IOW, I don't think the discussion, such as it was, was detailed
enough, and I won't be surprised if people didn't really understand
what we are going to change and how.  This gap needs to be filled
before we can conclude that "everyone is in favor".

Thanks.

Re: Signing git tags for releases

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 1540 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Wed, 8 Dec 2021 14:06:33 -0800
>> Cc: emacs-devel@gnu.org
>>
>> There have been no other comments within a week, besides the one from
>> Teemu Likonen who spotted a mistake in the patch I proposed.
>>
>> If anyone has anything more to add here, there is still some time to
>> speak up before it is time for the second pretest.  If I don't see any
>> further comments until then, I will go ahead with the proposed plan.
>
> At least one important aspect remains un-discussed: how do we make
> sure the keys of those who sign tags are made available for the
> others, who'd like to verify the signatures.  This will have to be
> described in CONTRIBUTE, with enough detail for people to follow even
> if they aren't experts in GnuPG use.
>
> More generally, what exactly is proposed?  I think it would be good to
> see some text for CONTRIBUTE and/or make-tarball.txt (or other docs)
> with what will be the procedures related to this.

I did include a patch in my first message; I have included it again
below with the fix from Teemu.

In this new patch, I also added instructions for how to verify a tag to
CONTRIBUTE.

> IOW, I don't think the discussion, such as it was, was detailed
> enough, and I won't be surprised if people didn't really understand
> what we are going to change and how.  This gap needs to be filled
> before we can conclude that "everyone is in favor".

I hope the attached patch will clear up any remaining doubts.  Thanks.

[-- Attachment #2: sign-2.diff --]
[-- Type: text/x-diff, Size: 2421 bytes --]

diff --git a/CONTRIBUTE b/CONTRIBUTE
index 7c3421ed75..5dbcb469e0 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -366,6 +366,18 @@ reasons.  These should be marked by including something like "Do not
 merge to master" or anything that matches gitmerge-skip-regexp (see
 admin/gitmerge.el) in the commit message.
 
+** Git tags
+
+Git tags are used for released versions of Emacs, including pretests
+and release candidates.  To list them, type "git tag" or "git tag -n".
+
+Recent tags are signed for additional security.  To verify a
+signature, type "git tag -v TAGNAME".  You will first need to fetch
+the public key used to sign the tag, using something like:
+
+  gpg --keyserver pgp.mit.edu --recv-keys \
+    CEA1DE21AB108493CC9C65742E82323B8F4353EE
+
 ** GNU ELPA
 
 This repository does not contain the Emacs Lisp package archive
diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index 872cb00ca2..5350ddc962 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -187,7 +187,7 @@ General steps (for each step, check for possible errors):
 8.  You can now tag the release/pretest and push it together with the
     last commit:
 
-     cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
+     cd EMACS_ROOT_DIR && git tag -s TAG -m "Emacs TAG"
      git push
      git push --tags
 
@@ -199,16 +199,20 @@ General steps (for each step, check for possible errors):
     use the SHA1 of the last commit which went into the release
     tarball, in case there were some intervening commits since then:
 
-     git tag -a TAG -m "Emacs TAG" SHA1
+     git tag -s TAG -m "Emacs TAG" SHA1
      git push --tags
 
     In the past, we were not always consistent with the annotation
     (i.e. -m "Emacs TAG").  The preferred format is like this for a
     pretest, release candidate and final release:
 
-     git tag -a emacs-28.0.90  -m "Emacs 28.0.90 pretest"
-     git tag -a emacs-28.1-rc1 -m "Emacs 28.1 RC1"
-     git tag -a emacs-28.1     -m "Emacs 28.1 release"
+     git tag -s emacs-28.0.90  -m "Emacs 28.0.90 pretest"
+     git tag -s emacs-28.1-rc1 -m "Emacs 28.1 RC1"
+     git tag -s emacs-28.1     -m "Emacs 28.1 release"
+
+    The "-s" option above means to sign the tag using your default GPG
+    key.  Make sure this uses the same GPG key that you use to sign
+    the release (see below).
 
 9. Decide what compression schemes to offer.
     For a release, at least gz and xz:

Re: Signing git tags for releases

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 26 Dec 2021 08:56:18 -0800
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> I hope the attached patch will clear up any remaining doubts.  Thanks.

Some comments below.

> +Recent tags are signed for additional security.  To verify a
> +signature, type "git tag -v TAGNAME".  You will first need to fetch
> +the public key used to sign the tag, using something like:
> +
> +  gpg --keyserver pgp.mit.edu --recv-keys \
> +    CEA1DE21AB108493CC9C65742E82323B8F4353EE

This should explain where did that long hex string come from, and how
it is related to some particular signed tag.

> -     cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
> +     cd EMACS_ROOT_DIR && git tag -s TAG -m "Emacs TAG"

Won't Git then ask for some input?  IOW, does this describe the
interaction completely enough for the person who does this the first
time to know what to do?  And what about the preparations, like making
sure one has GnuPG, having a key available, etc.?  The first time I
needed to upload an Emacs tarball (which also needs to be signed), I
needed to read quite a lot on how to use GnuPG, how to generate a key,
how to use it, etc.

And finally, is signing the tags a requirement?  Is it possible to
commit an unsigned tag for pretest or release?

> +     git tag -s emacs-28.0.90  -m "Emacs 28.0.90 pretest"
> +     git tag -s emacs-28.1-rc1 -m "Emacs 28.1 RC1"
> +     git tag -s emacs-28.1     -m "Emacs 28.1 release"
> +
> +    The "-s" option above means to sign the tag using your default GPG
> +    key.

What if the person has more than one key?

>            Make sure this uses the same GPG key that you use to sign
> +    the release (see below).

This might not be possible, if the person who tags the release/pretest
doesn't have an uploader key.  Also, the pointer to "below" may not be
accurate enough, because "sign the release" as a phrase doesn't appear
anywhere, and references to "key" are many enough to confuse.  This
must be explained in the clearest terms, because people who are not
used to sign stuff will be nervous and stressed when required to do
this.

Re: Signing git tags for releases

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Some comments below.

Thanks.

>> +Recent tags are signed for additional security.  To verify a
>> +signature, type "git tag -v TAGNAME".  You will first need to fetch
>> +the public key used to sign the tag, using something like:
>> +
>> +  gpg --keyserver pgp.mit.edu --recv-keys \
>> +    CEA1DE21AB108493CC9C65742E82323B8F4353EE
>
> This should explain where did that long hex string come from, and how
> it is related to some particular signed tag.

How about adding:

    The last argument to the above command should be the id of the key
    used to sign the tag you want to verify.

>> -     cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
>> +     cd EMACS_ROOT_DIR && git tag -s TAG -m "Emacs TAG"
>
> Won't Git then ask for some input?  IOW, does this describe the
> interaction completely enough for the person who does this the first
> time to know what to do?

This describes the full interaction, except for the password prompt.

> And what about the preparations, like making
> sure one has GnuPG, having a key available, etc.?  The first time I
> needed to upload an Emacs tarball (which also needs to be signed), I
> needed to read quite a lot on how to use GnuPG, how to generate a key,
> how to use it, etc.

Yeah, GnuPG is... a lot to wrap your head around.  That is unfortunately
the case whether we sign tags or not.

Documenting all the things you talk about sounds to me like a
significant effort, which risk duplicating tutorials and documentation
for gpg itself.  I suggest not doing that, not least because I don't
feel comfortable writing such a tutorial.  Though I won't object if
someone wants to write such a tutorial or perhaps better point out a
good existing one that we could refer to.

> And finally, is signing the tags a requirement?  Is it possible to
> commit an unsigned tag for pretest or release?

Nothing will technically stop us from doing that, but I think we might
as well make signing into a requirement.  The person doing the release
will need to have a gpg key in any case, so it is not more work.

>> +     git tag -s emacs-28.0.90  -m "Emacs 28.0.90 pretest"
>> +     git tag -s emacs-28.1-rc1 -m "Emacs 28.1 RC1"
>> +     git tag -s emacs-28.1     -m "Emacs 28.1 release"
>> +
>> +    The "-s" option above means to sign the tag using your default GPG
>> +    key.
>
> What if the person has more than one key?

No idea, but here's what "man git-tag" has to say:

       -s, --sign
           Make a GPG-signed tag, using the default e-mail address’s key. The
           default behavior of tag GPG-signing is controlled by tag.gpgSign
           configuration variable if it exists, or disabled otherwise. See
           git-config(1).

>>            Make sure this uses the same GPG key that you use to sign
>> +    the release (see below).
>
> This might not be possible, if the person who tags the release/pretest
> doesn't have an uploader key.  Also, the pointer to "below" may not be
> accurate enough, because "sign the release" as a phrase doesn't appear
> anywhere, and references to "key" are many enough to confuse.  This
> must be explained in the clearest terms, because people who are not
> used to sign stuff will be nervous and stressed when required to do
> this.

I can only agree about the nervous and stressed part.  The entire
release process is somewhat nerve-racking, and having to deal with gpg
doesn't make things any easier.

For simplicity and convenience, I think it is better if we try to ensure
that only one person is signing things per release.  It's probably okay
that someone else signs the release tag, but I'd hope that it's someone
who's already configured gpg and is at least somewhat familiar with the
release process.

Re: Signing git tags for releases

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 26 Dec 2021 13:33:03 -0800
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> >> +Recent tags are signed for additional security.  To verify a
> >> +signature, type "git tag -v TAGNAME".  You will first need to fetch
> >> +the public key used to sign the tag, using something like:
> >> +
> >> +  gpg --keyserver pgp.mit.edu --recv-keys \
> >> +    CEA1DE21AB108493CC9C65742E82323B8F4353EE
> >
> > This should explain where did that long hex string come from, and how
> > it is related to some particular signed tag.
> 
> How about adding:
> 
>     The last argument to the above command should be the id of the key
>     used to sign the tag you want to verify.

I'd prefer something that started with a command whose output shows
that key, which would then prompt the user to fetch the key.

> >> -     cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
> >> +     cd EMACS_ROOT_DIR && git tag -s TAG -m "Emacs TAG"
> >
> > Won't Git then ask for some input?  IOW, does this describe the
> > interaction completely enough for the person who does this the first
> > time to know what to do?
> 
> This describes the full interaction, except for the password prompt.

I suggest to say that, something like

  GnuPG may ask for the key password.

> > And what about the preparations, like making
> > sure one has GnuPG, having a key available, etc.?  The first time I
> > needed to upload an Emacs tarball (which also needs to be signed), I
> > needed to read quite a lot on how to use GnuPG, how to generate a key,
> > how to use it, etc.
> 
> Yeah, GnuPG is... a lot to wrap your head around.  That is unfortunately
> the case whether we sign tags or not.
> 
> Documenting all the things you talk about sounds to me like a
> significant effort, which risk duplicating tutorials and documentation
> for gpg itself.

Isn't that just a few commands?  We don't need to explain anything,
just to give a cookbook-stile list of instructions to follow.

> For simplicity and convenience, I think it is better if we try to ensure
> that only one person is signing things per release.

That doesn't work when that person steps down and someone else steps
up to the job.  Which is more or less the only situation where those
instructions are really important.

So any clarifications and cookbook-style instructions are bonus, I
think.

Thanks.