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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 10, 2023, 19:25 UTC
Message-ID: <xmqqfsbdiaqd.fsf@gitster.g>
In-Reply-To: <20230210061611.124932-1-gwymor@tilde.club>

Gwyneth Morgan <gwymor@tilde.club> writes:

Show 22 quoted lines

> This document only explained PGP signatures, but Git now supports X.509
> and SSH signatures.
>
> 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 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.

OK, we used to say "begin with <<something PGP>>" that was not generic, so we borrow the "ascii armor header/tail line" term the crypto folks use. Then ...

> +PGP::
> +	Signatures begin with `-----BEGIN PGP SIGNATURE-----` and end
> +	with `-----END PGP SIGNATURE-----`, unless gpg is told to

... it may be easier to understand if the paragraph somehow made it clear that "ascii armore header" is "-----BEGIN PGP SIGNATURE-----" and "tail" is "---END PGP SIGNATURE-----" for the format being described.

Alternatively, if we are going to repeat "... begin with X, and end with Y" for each format, then we may not even need to have the previous paragraph that says these formats follow the same pattern (i.e. header then contents then tail, but header and tail are different depending on the format).

Show 10 quoted lines

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