Re: [PATCH v2] signature-format.txt: note SSH and X.509 signature delimiters

From: Gwyneth Morgan <gwymor@tilde.club>
Date: Feb 27, 2023, 20:26 UTC
Message-ID: <Y/0R3lDyJrtd4gIZ@tilde.club>
In-Reply-To: <230210.86ilg9wzho.gmgdl@evledraar.gmail.com>

On 2023-02-10 11:52:42+0100, Ævar Arnfjörð Bjarmason wrote:

Show 13 quoted lines

> 
> On Fri, Feb 10 2023, Gwyneth Morgan wrote:
> 
> > This document only explained PGP signatures, but Git now supports X.509
> > and SSH signatures.
> 
> To elaborate a bit, in 1e7adb97566 (gpg-interface: introduce new
> signature format "x509" using gpgsm, 2018-07-17) we added X.509, and in
> 29b315778e9 (ssh signing: add ssh key format and signing code,
> 2021-09-10) we added "ssh", but our docs were never updated.
> 
> Your commit message says as much in briefer terms, but maybe if you
> re-roll having those references would help put this change in context.>

I'll reference those commits in v3.

Show 7 quoted lines

> > +Signatures begin with an ASCII Armor header line and end with a tail line,
> > +which differ depending on signature type.
> 
> Does the "ASCII Armor header" really add something here, or just confuse
> the user with a reference that's not followed-up or explained here?
> Maybe we should point out OpenPGP's '--armor' option in passing, to note
> to the reader that this isn't some git-specific concept.

I think having a relevant term to search for online and in manpages is helpful. Mentioning the specific command-line option seems unnecessary, but I'll put the term "ASCII Armor" in quotes to make it clearer that this is not a git-specific concept.

Show 17 quoted lines

> I wonder if structuring it like this wouldn't help make this easier to
> read, and reduce the repetition, as well as making the circular
> references between this & 'gpg.format' more obvious:
> 
> 	The signature start and end marker comes on its own line, and
> 	differs based on the signature type (as selected by
> 	'gpg.format', see linkgit:git-config[1]).
> 
>         Those are, for values of 'gpg.format':
> 
>         gpg: `-----BEGIN PGP SIGNATURE-----` and `-----END PGP
>              SIGNATURE-----`. Or, if GPG has been asked to produce
>              RFC1991 signatures: `-----BEGIN PGP MESSAGE-----` and
>              `-----END PGP MESSAGE-----`
> 
>         x509: `-----BEGIN SIGNED MESSAGE-----` `-----END SIGNED MESSAGE-----`
> 	ssh:`-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----`

Looks good. I'll do this in v3. I'll reference these by the gpg.format value, as well as a parenthetical proper name, like "gpg (PGP)"; these are basically the same the other two formats, but I want it to be clear that `gpg` signatures don't have to be from the gpg program but could be from any PGP-supporting program.

> Then for gpg.format in Documentation/config/gpg.txt we could add e.g.:
> 
> 	See linkgit:gitformat-signature[5] for the signature format,
> 	which differs based on the selected 'gpg.format'.

OK.

Thanks.