Re: [PATCH v2] signature-format.txt: note SSH and X.509 signature delimiters
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.>
Show 25 quoted lines
> 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.
Show 13 quoted lines
> +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'.
Gwyneth Morgan
