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

From: Gwyneth Morgan <gwymor@tilde.club>
Date: Feb 10, 2023, 06:16 UTC
Message-ID: <Y+XhPeh76D6/Uz6C@tilde.club>
In-Reply-To: <xmqq7daui4s8.fsf@gitster.g>

On 2022-01-20 11:30:15-0800, Junio C Hamano wrote:

Show 10 quoted lines

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

I believe the existing language is referring to the "-----BEGIN PGP MESSAGE-----" format GPG outputs in RFC 1991 mode, rather than the "-----BEGIN SIGNED MESSAGE-----" that X.509 uses.

Show 25 quoted lines

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

OpenSSH's signature format documentation says:

	The Armored SSH signatures consist of a header, a base64
	encoded blob, and a footer.

	The header is the string "-----BEGIN SSH SIGNATURE-----"
	followed by a newline. The footer is the string
	"-----END SSH SIGNATURE-----" immediately after a newline.
(https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.sshsig?rev=1.4&content-type=text/x-cvsweb-markup)

This is sufficiently similar to the nomenclature in RFC 4880 to call these "Armor Header Line and Tail Line" without any misunderstanding (or "footer line" if that's preferred). I did not find documentation on what X.509 calls these.