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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 20, 2022, 19:30 UTC
Message-ID: <xmqq7daui4s8.fsf@gitster.g>
In-Reply-To: <20220120053223.221667-1-gwymor@tilde.club>

Gwyneth Morgan <gwymor@tilde.club> 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 ;-)

Show 17 quoted lines

> Signed-off-by: Gwyneth Morgan <gwymor@tilde.club>
> ---
>  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.

Show 18 quoted lines

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