How to gpg signed email patches?

How to gpg signed email patches?

[Klaus Frank]

Hi,

how do I get "git send-email" to send the patches gpg signed? I tried
first signing the commit but after spending time looking into the
documentation I couldn't work out how to do it. All I discovered so far
is that the "git send-email" appears to be using "git format-patch"
internally and that's where it currently gets lost.

Sadly none of the man pages I looked at so far mentions anything about
gpg signing in this regards. Not even "git am" does.

Ideally I'd like to have "git send-email" send my patches gpg-signed to
ensure authenticity and integrity.

I also considered alternatives like using my MTA to GPG-Sign these mails
however as the "git am" documentation also didn't mention gpg signing I
refrained from it to avoid breaking it and causing issues for anyone
receiving that patch. Same for sending it using "git pack".

Is this currently a limitation or am I just doing it wrong?

Sincerely,
Klaus Frank

Re: How to gpg signed email patches?

[Matt Hunter]

Hi

On Sun Apr 13, 2025 at 3:17 PM EDT, Klaus Frank wrote:
> how do I get "git send-email" to send the patches gpg signed? I tried
> first signing the commit but after spending time looking into the
> documentation I couldn't work out how to do it. All I discovered so far
> is that the "git send-email" appears to be using "git format-patch"
> internally and that's where it currently gets lost.

There's a conceptual issue with mailing patches from signed commits.
Once your patch recipient goes to apply it to their branch, they are
recorded as the "committer" identity of the new commit object.  This
would break the validity of any existing signature.

This is likely the reason by the related git tools (format-patch, am)
ignore this information.

You may have also noticed that commands like git-rebase and
git-cherry-pick will drop signatures from commits as well, since they
are being replayed onto a different history, changing the commit data.

Re: How to gpg signed email patches?

[brian m. carlson]

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

On 2025-04-13 at 19:17:26, Klaus Frank wrote:
> Hi,

Hi,

> how do I get "git send-email" to send the patches gpg signed? I tried
> first signing the commit but after spending time looking into the
> documentation I couldn't work out how to do it. All I discovered so far
> is that the "git send-email" appears to be using "git format-patch"
> internally and that's where it currently gets lost.
> 
> Sadly none of the man pages I looked at so far mentions anything about
> gpg signing in this regards. Not even "git am" does.
> 
> Ideally I'd like to have "git send-email" send my patches gpg-signed to
> ensure authenticity and integrity.
> 
> I also considered alternatives like using my MTA to GPG-Sign these mails
> however as the "git am" documentation also didn't mention gpg signing I
> refrained from it to avoid breaking it and causing issues for anyone
> receiving that patch. Same for sending it using "git pack".
> 
> Is this currently a limitation or am I just doing it wrong?

I don't think Git supports this out of the box.  The proper way to do
this would be via PGP/MIME, since clearsigning the patches would result
in them not applying properly (due to the dashes being escaped).

More notably, I've had problems applying patches that are signed using
PGP/MIME because `git am` doesn't seem to understand how to extract the
data in all cases (maybe it does in some cases, but I haven't tested).
As a practical matter, signing PGP/MIME requires that the enclosing body
be encoded as either quoted-printable (recommended) or base64 (not
recommended because plain text as base64 tends to be a sign of spam)
because that prevents breakage from intervening mail servers and
that can introduce some trickiness in extracting the text without
parsing the MIME structure.

I know that Git definitely does not know how to verify those signatures,
though, so many people would end up not verifying them.

The discussion on the list in the past has generally not been in favour
of this approach, since the assumption is that the patch is accepted
based on whether it is good or not and not whether it is authentic.  I
acknowledge that there are workflows where authenticity is useful,
though, so I would not be opposed to seeing patches to implement this,
but I'm afraid that it has yet to be implemented.

An alternative approach, which has also been discussed (and which I
might end up sending a patch for at some point), is including committer,
signature, and base commit data in email headers to allow reconstructing
the exact commit with a valid signature.  Whether the maintainer chooses
to keep that signature is of course up to them, but this would allow
the commit to be verified using the normal mechanism.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

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

Re: How to gpg signed email patches?

[Klaus Frank]

On 2025-04-14 00:21:46, Matt Hunter wrote:
> Hi
> There's a conceptual issue with mailing patches from signed commits.
> Once your patch recipient goes to apply it to their branch, they are
> recorded as the "committer" identity of the new commit object.  This
> would break the validity of any existing signature.

You're right on that part. However even though it would be nice to
get the signed commit into the public repo my main focus here was
more to ensure integrity and authenticity until it is processed by
the project maintainers. E.g. it didn't get mangled by some thing on
the way and I wasn't impersonated by someone else. E.g. I was
mainly focusing on allowing the ones accepting my patch to know it
is from me and it hasn't been tampered with on the way. E.g. by a mail
server screwing with the mail content or some middle box that inserted
or rewrote parts of the message...

> This is likely the reason by the related git tools (format-patch, am)
> ignore this information.
Ok, how do others deal with that scenario then? Not an issue?
> You may have also noticed that commands like git-rebase and
> git-cherry-pick will drop signatures from commits as well, since they
> are being replayed onto a different history, changing the commit data.

True, but thouse commands to not pass information through a
lossy and "tampery" media like email. It stays local. My main focus
was on the transfer from my git repo to the (git repo of) other
devs on the project. And lesser on it being preserved after the
merge.

When a project uses a forge like github or gitlab this is basically
not such an issue because of TLS and having to have a
user account on it (and it preserving the pgp signature up until the
last click before being merged in)

Re: How to gpg signed email patches?

[Klaus Frank]

On 2025-04-14 00:52:42, brian m. carlson wrote:
> On 2025-04-13 at 19:17:26, Klaus Frank wrote:
>> Hi,
>>
>> I don't think Git supports this out of the box.  The proper way to do
>> this would be via PGP/MIME, since clearsigning the patches would result
>> in them not applying properly (due to the dashes being escaped).
But if "git am" would support pgp clearsigning it could just easily 
reverse that, no?
But I've to admit I didn't fully look into all of the escape rules and their
reversability yet. Is RFC 4880 Section-7 the correct one for clearsign
and RFC 3156 Section-5 the correct one for PGP/MIME?
>> More notably, I've had problems applying patches that are signed using
>> PGP/MIME because `git am` doesn't seem to understand how to extract the
>> data in all cases (maybe it does in some cases, but I haven't tested).
>> As a practical matter, signing PGP/MIME requires that the enclosing body
>> be encoded as either quoted-printable (recommended) or base64 (not
>> recommended because plain text as base64 tends to be a sign of spam)
>> because that prevents breakage from intervening mail servers and
>> that can introduce some trickiness in extracting the text without
>> parsing the MIME structure.
>>
>> I know that Git definitely does not know how to verify those signatures,
>> though, so many people would end up not verifying them.

Yea, then better just not include them for now.
Including them sounds like a shitty move towards or better
against the other developers. Kinda but not quite maliciouse compliance
style. :/

>> The discussion on the list in the past has generally not been in favour
>> of this approach, since the assumption is that the patch is accepted
>> based on whether it is good or not and not whether it is authentic.  I
>> acknowledge that there are workflows where authenticity is useful,
>> though, so I would not be opposed to seeing patches to implement this,
>> but I'm afraid that it has yet to be implemented.
That may be, however the signature also shows if it has been damaged
in transit and that is at least in my eyes a very valuable information.
(And maybe in the near future to mandate everyone signs (or even
encrypt) their contributions in order to easily ban "vibe coders")
>> An alternative approach, which has also been discussed (and which I
>> might end up sending a patch for at some point), is including committer,
>> signature, and base commit data in email headers to allow reconstructing
>> the exact commit with a valid signature.  Whether the maintainer chooses
>> to keep that signature is of course up to them, but this would allow
>> the commit to be verified using the normal mechanism.

That sounds also good compared to what I scetched up so far.
This is what I was thinking about btw (nothing special really):

On the sender side:
1. "git format-patch"/"git send-email" sees that the commit{s} is/are 
signed or it was executed with an explicit flag to sign (similar to 
git-commit "-S[<key-id>], --gpg-sign[=<key-id>], --no-gpg-sign")
2. Either "git format-patch":
  a. Somehow embedds the commit signature as plain text [Your suggestion].
  b. Does "gpg --sign --clear-sign --include-key-block" the entire 
email (Or [rfc4880#section-7]).
  c. When "--inline" is specified {multipart message} it creates a 
detached signature ("gpg --sign --detach-sign --include-key-block 
--armor") and attach it as a 3rd "application/pgp-signature" part to the 
multipart-message (or [RFC3156#Section-5] instead of literally "just" 
attaching an additional .sig file to the mail)
3. Send the mail
Also "git format-patch" propably should support these gpg commandline 
properties: `--homedir`, `--keyring`, `--primary-keyring`, 
`--refresh-keys`, `--armor`, `--no-armor`.

On the receiver side when running e.g. "git am":
On a mail without a signature
=> Fallback to current behaviour accept (maybe have an optional 
configurable warning message). And have an option to enforce signatures 
(fail if enforced and missing).
On a mail with a signature:
a. If nothing else specified default to e.g. `gpg --verify --batch 
--auto-key-import --auto-key-retrieve --tofu-default-policy="auto" 
--trust-model="tofu+pgp"` (marginally trust all keys and build a web of 
trust; Maybe on a dedicated gpg-homedir/keyring)
b. If operating on the users generic gpg-homedir/keyring or explicitly 
specified use `--tofu-default-policy="unknown"` instead of "auto". This 
will still import and validate keys from the signatures [depending on 
user system config also from keyserver, ldap, ... but disabled by 
default] but any key the user didn't touch themselves will be considered 
"unknown" trusted and therefore won't be used for extending the web of 
trust.
c. also have flags for these gpg commandline properties: `--homedir`, 
`--keyring`, `--primary-keyring`, `--refresh-keys`.
d. maybe also add pgp-encryption support (to also accept e.g. patches 
for zero days?). All that would be needed for that is "git am" would 
have to tell gpg to try to decript the message and similar "git 
format-patch" would need one to encrypt.


Sincerely,
Klaus Frank

Re: How to gpg signed email patches?

[brian m. carlson]

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

On 2025-04-14 at 00:23:02, Klaus Frank wrote:
> But if "git am" would support pgp clearsigning it could just easily reverse
> that, no?

Yes, but not everybody has GnuPG installed on their system.  It doesn't
come by default on macOS and people will want to parse the emails and
apply the patches nonetheless.

> But I've to admit I didn't fully look into all of the escape rules and their
> reversability yet. Is RFC 4880 Section-7 the correct one for clearsign
> and RFC 3156 Section-5 the correct one for PGP/MIME?

Yes, although RFC 9580 has superseded RFC 4880.

> That may be, however the signature also shows if it has been damaged
> in transit and that is at least in my eyes a very valuable information.
> (And maybe in the near future to mandate everyone signs (or even
> encrypt) their contributions in order to easily ban "vibe coders")

I agree that it detects patches that have been damaged in transit, which
is valuable, but it also throws a bunch of complexity into the process.

> > > An alternative approach, which has also been discussed (and which I
> > > might end up sending a patch for at some point), is including committer,
> > > signature, and base commit data in email headers to allow reconstructing
> > > the exact commit with a valid signature.  Whether the maintainer chooses
> > > to keep that signature is of course up to them, but this would allow
> > > the commit to be verified using the normal mechanism.
> 
> That sounds also good compared to what I scetched up so far.
> This is what I was thinking about btw (nothing special really):

My approach also has the benefit that it works for SSH commit
signatures, which PGP/MIME and S/MIME do not.  I think many people find
SSH signatures to be easier to use than OpenPGP or X.509 and SSH signing
is easier to do when one's working in a remote dev environment (just
forward your agent).

> On the sender side:
> 1. "git format-patch"/"git send-email" sees that the commit{s} is/are signed
> or it was executed with an explicit flag to sign (similar to git-commit
> "-S[<key-id>], --gpg-sign[=<key-id>], --no-gpg-sign")
> 2. Either "git format-patch":
>   a. Somehow embedds the commit signature as plain text [Your suggestion].
>   b. Does "gpg --sign --clear-sign --include-key-block" the entire email (Or
> [rfc4880#section-7]).
>   c. When "--inline" is specified {multipart message} it creates a detached
> signature ("gpg --sign --detach-sign --include-key-block --armor") and
> attach it as a 3rd "application/pgp-signature" part to the multipart-message
> (or [RFC3156#Section-5] instead of literally "just" attaching an additional
> .sig file to the mail)

This isn't the entirety of how it works.  I believe the headers of the
internal part (e.g., Content-Type and Content-Transfer-Encoding) are
also signed in PGP/MIME; that is, it's the entire body part, headers and
all.

> 3. Send the mail
> Also "git format-patch" propably should support these gpg commandline
> properties: `--homedir`, `--keyring`, `--primary-keyring`, `--refresh-keys`,
> `--armor`, `--no-armor`.

Those arguments are really better left to a script that runs as
`gpg.program`.  There are other implementations of that software that
only support the bare minimum options (e.g., smimesign) and we want to
minimize the functionality that needs to be supported.  I have, for
instance, used a custom script to include a signature from the
environment that was generated on another machine.

That's another advantage to my approach: it avoids the necessity for
additional options to be supported.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

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

Re: How to gpg signed email patches?

[Konstantin Ryabitsev]

On Sun, Apr 13, 2025 at 07:17:26PM +0000, Klaus Frank wrote:
> how do I get "git send-email" to send the patches gpg signed?

You have to step back and ask what is the end-goal? Do you want
repudiation/attestation for your own patches, or do you want to be able to
verify that the patches sent to you by contributors are tamper-evident?

On the kernel side of things, we've been using patatt [1], which supports PGP,
SSH, and ed25519-signing of patches via a dedicated custom header, a-la DKIM.

[1] https://github.com/mricon/patatt/blob/main/README.rst

-K

Re: How to gpg signed email patches?

[Junio C Hamano]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

> On Sun, Apr 13, 2025 at 07:17:26PM +0000, Klaus Frank wrote:
>> how do I get "git send-email" to send the patches gpg signed?
>
> You have to step back and ask what is the end-goal? Do you want
> repudiation/attestation for your own patches, or do you want to be able to
> verify that the patches sent to you by contributors are tamper-evident?

Excellent question.  These are probably both addressed by signed
e-mails, but quite different from what object-level signing
(e.g. "git commit --signed") aims at.

> On the kernel side of things, we've been using patatt [1], which supports PGP,
> SSH, and ed25519-signing of patches via a dedicated custom header, a-la DKIM.
>
> [1] https://github.com/mricon/patatt/blob/main/README.rst
>
> -K

Re: How to gpg signed email patches?

[Junio C Hamano]

"Matt Hunter" <m@lfurio.us> writes:

> Hi
>
> On Sun Apr 13, 2025 at 3:17 PM EDT, Klaus Frank wrote:
>> how do I get "git send-email" to send the patches gpg signed? I tried
>> first signing the commit but after spending time looking into the
>> documentation I couldn't work out how to do it. All I discovered so far
>> is that the "git send-email" appears to be using "git format-patch"
>> internally and that's where it currently gets lost.
>
> There's a conceptual issue with mailing patches from signed commits.
> Once your patch recipient goes to apply it to their branch, they are
> recorded as the "committer" identity of the new commit object.  This
> would break the validity of any existing signature.
>
> This is likely the reason by the related git tools (format-patch, am)
> ignore this information.
>
> You may have also noticed that commands like git-rebase and
> git-cherry-pick will drop signatures from commits as well, since they
> are being replayed onto a different history, changing the commit data.

Very well said.  Protecting the e-mail with GPG is a job for
MUA/MSA, that is independent from signature used to sign objects
like commits and tags, so the signature over objects cannot be
reused by programs like send-email.

But send-email may not have an option to wrap its payload in s-mime
or pgp, which can be a separate project worth looking into.

Thanks.

Re: How to gpg signed email patches?

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> I know that Git definitely does not know how to verify those signatures,
> though, so many people would end up not verifying them.


True that many people would end up not verifying them, but I do not
think Git has much to do with that.

Some contributors seem to send PGP signed patches to this list (and
I once mildly asked them not to, but these days I simply do not
care), and if I had their public keys marked as trusted, my
mail-reading environment would do the verification for me totally
outside Git (as this part of the workflow is not about Git, but
about communicating over authenticated and cryptographically
protected messages, whose contents happen to be patches), and I'll
just "git am" knowing that the patch is from the contributor who has
access to that trusted key.

The "key" (no pun intended) in the above is "if I had" part.  The
overhead of retrieving, validating, and keeping the key for a
contributor becomes worth it only after the contributor turns out to
be very prolific one.  The Web of trust, while was very attractive
as a concept, is not so convenient to maintain well enough to be
relied on as an infrastructure.