| Message ID | 20220120053223.221667-1-gwymor@tilde.club (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | signature-format.txt: Note SSH and X.509 signature delimiters | expand |
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 ;-) > 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. > +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
Junio C Hamano <gitster@pobox.com> writes: >> +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. Please do not take this as my recommendation to blindly adopt "Armor Header" etc. It was merely an illustration of what level of due diligence is expected behind a change in this project. If you make a similar study of nomenclature used by X.509 and SSH folks, you may discover that there is no agreed-upon standard term common across these three, in which case "signature delimiter" might be the best "vendor neutral" word to use in our documentation. Or it may turn out that RFC4880 is the oddball and the other two use the same words to refer to their header and tail lines, in which case, unless those common words are too technical and hard to understand for readers, we may want to use that common one. Thanks.
On 2022-01-20 11:30:15-0800, Junio C Hamano wrote: > 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. > > 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.
Gwyneth Morgan <gwymor@tilde.club> writes: > 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. The paragraph came from 76f9d8ba (Documentation/technical: describe signature formats, 2016-06-17) that started the documentation, and predates x509 support by two years (and ssh came even later), so you're right. It couldn't possibly have meant anything newer. Thanks. > 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. > > 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. Sounds good. Thanks for due dilligence; it would make sure our nomenclature would not go out of line without a good reason.
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 +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
This document only explained PGP signatures, but Git now supports X.509 and SSH signatures. Signed-off-by: Gwyneth Morgan <gwymor@tilde.club> --- Documentation/technical/signature-format.txt | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-)