Subject: Re: [PATCH] signature-format.txt: Note SSH and X.509 signature delimiters

From: Junio C Hamano <[email-masked]>
Date: Thu, 20 Jan 2022 11:30:15 -0800

Gwyneth Morgan <[email-masked]> writes:

> Subject: Re: [PATCH] signature-format.txt: Note SSH and X.509 signature delimiters

Convention: downcase "N" in "Note".

> This document only explained PGP signatures, but Git now supports X.509
> and SSH signatures.

This is technically incorrect as the original text does talk about
MESSAGE that is used by X.509.

But the change does make it more clear to help readers not to make
the same mistake as the above sentence.  In 3-item enumeration, it
is very clear what we now support ;-)

> Signed-off-by: Gwyneth Morgan <[email-masked]>
> ---
>  Documentation/technical/signature-format.txt | 19 ++++++++++++++++---
>  1 file changed, 16 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt
> index 166721be6f..c148d4c750 100644
> --- a/Documentation/technical/signature-format.txt
> +++ b/Documentation/technical/signature-format.txt
> @@ -9,9 +9,22 @@ 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`.
> +Signatures always begin and end with a delimiter, which differs

The term "signature delimiter" is understandable, but is that the
term used by the users and the developers of OpenPGP, X.509 and SSH
who know and use such an ascii-armored signatures?  Just making sure
we do not accidentally "invent" a new word that the upstream/wider
community has an established word for.

	... Goes and looks ...
	https://www.rfc-editor.org/rfc/rfc4880.html#section-7
	seems to use "Armor Header and Armor Tail Lines" to refer to
	the BEGIN and the END delimiter lines, respectively.

Other than that, the patch looks good to me.

Thanks.

> +depending on signature type.
> +
> +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-----`.
>  
>  Signatures sometimes appear as a part of the normal payload
>  (e.g. a signed tag has the signature block appended after the payload