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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

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

> Signed-off-by: Gwyneth Morgan <gwymor@tilde.club>
> ---
>  Documentation/gitformat-signature.txt | 26 ++++++++++++++++++++------
>  1 file changed, 20 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt
> index d8e3eb1bac..5f0c9202e3 100644
> --- a/Documentation/gitformat-signature.txt
> +++ b/Documentation/gitformat-signature.txt
> @@ -17,12 +17,26 @@ DESCRIPTION
>  Git uses cryptographic signatures in various places, currently objects (tags,
>  commits, mergetags) and transactions (pushes). In every case, the command which
>  is about to create an object or transaction determines a payload from that,
> -calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and
> -embeds the signature into the object or transaction.
> -
> -Signatures always begin with `-----BEGIN PGP SIGNATURE-----`
> -and end with `-----END PGP SIGNATURE-----`, unless gpg is told to
> -produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.
> +calls an external program to obtain a detached signature for the payload
> +(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the
> +object or transaction.
> +
> +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.

> +PGP::
> +	Signatures begin with `-----BEGIN PGP SIGNATURE-----` and end
> +	with `-----END PGP SIGNATURE-----`, unless gpg is told to
> +	produce RFC1991 signatures which use `MESSAGE` instead of
> +	`SIGNATURE`.
> +
> +SSH::
> +	Signatures begin with `-----BEGIN SSH SIGNATURE-----` and end
> +	with `-----END SSH SIGNATURE-----`.
> +
> +X.509::
> +	Signatures begin with `-----BEGIN SIGNED MESSAGE-----` and end
> +	with `-----END SIGNED MESSAGE-----`.

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-----`

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'.