{"thread":{"id":"57274","subject":"[PATCH] signature-format.txt: Note SSH and X.509 signature delimiters","startedAt":"2022-01-20T05:33:47Z","lastAt":"2023-02-27T21:44:49Z","messageCount":11,"participants":["Gwyneth Morgan","Junio C Hamano","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"446537","messageId":"20220120053223.221667-1-gwymor@tilde.club","threadId":"57274","inReplyTo":null,"subject":"[PATCH] signature-format.txt: Note SSH and X.509 signature delimiters","fromName":"Gwyneth Morgan","fromEmail":"gwymor@tilde.club","sentAt":"2022-01-20T05:32:24Z","receivedAt":"2022-01-20T05:33:47Z","isPatch":true,"sender":{"key":"gwymor@tilde.club","avatar":"https://avatars.githubusercontent.com/u/87623694?v=4"},"body":"This document only explained PGP signatures, but Git now supports X.509\nand SSH signatures.\n\nSigned-off-by: Gwyneth Morgan \n---\n Documentation/technical/signature-format.txt | 19 ++++++++++++++++---\n 1 file changed, 16 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt\nindex 166721be6f..c148d4c750 100644\n--- a/Documentation/technical/signature-format.txt\n+++ b/Documentation/technical/signature-format.txt\n@@ -9,9 +9,22 @@ is about to create an object or transaction determines a payload from that,\n calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and\n embeds the signature into the object or transaction.\n \n-Signatures always begin with `-----BEGIN PGP SIGNATURE-----`\n-and end with `-----END PGP SIGNATURE-----`, unless gpg is told to\n-produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.\n+Signatures always begin and end with a delimiter, which differs\n+depending on signature type.\n+\n+PGP::\n+\tSignatures begin with `-----BEGIN PGP SIGNATURE-----` and end\n+\twith `-----END PGP SIGNATURE-----`, unless gpg is told to\n+\tproduce RFC1991 signatures which use `MESSAGE` instead of\n+\t`SIGNATURE`.\n+\n+SSH::\n+\tSignatures begin with `-----BEGIN SSH SIGNATURE-----` and end\n+\twith `-----END SSH SIGNATURE-----`.\n+\n+X.509::\n+\tSignatures begin with `-----BEGIN SIGNED MESSAGE-----` and end\n+\twith `-----END SIGNED MESSAGE-----`.\n \n Signatures sometimes appear as a part of the normal payload\n (e.g. a signed tag has the signature block appended after the payload\n"},{"id":"446595","messageId":"xmqq7daui4s8.fsf@gitster.g","threadId":"57274","inReplyTo":"20220120053223.221667-1-gwymor@tilde.club","subject":"Re: [PATCH] signature-format.txt: Note SSH and X.509 signature delimiters","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-01-20T19:30:15Z","receivedAt":"2022-01-20T19:30:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Gwyneth Morgan writes:\n\n> Subject: Re: [PATCH] signature-format.txt: Note SSH and X.509 signature delimiters\n\nConvention: downcase \"N\" in \"Note\".\n\n> This document only explained PGP signatures, but Git now supports X.509\n> and SSH signatures.\n\nThis is technically incorrect as the original text does talk about\nMESSAGE that is used by X.509.\n\nBut the change does make it more clear to help readers not to make\nthe same mistake as the above sentence. In 3-item enumeration, it\nis very clear what we now support ;-)\n\n> Signed-off-by: Gwyneth Morgan \n> ---\n> Documentation/technical/signature-format.txt | 19 ++++++++++++++++---\n> 1 file changed, 16 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt\n> index 166721be6f..c148d4c750 100644\n> --- a/Documentation/technical/signature-format.txt\n> +++ b/Documentation/technical/signature-format.txt\n> @@ -9,9 +9,22 @@ is about to create an object or transaction determines a payload from that,\n> calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and\n> embeds the signature into the object or transaction.\n> \n> -Signatures always begin with `-----BEGIN PGP SIGNATURE-----`\n> -and end with `-----END PGP SIGNATURE-----`, unless gpg is told to\n> -produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.\n> +Signatures always begin and end with a delimiter, which differs\n\nThe term \"signature delimiter\" is understandable, but is that the\nterm used by the users and the developers of OpenPGP, X.509 and SSH\nwho know and use such an ascii-armored signatures? Just making sure\nwe do not accidentally \"invent\" a new word that the upstream/wider\ncommunity has an established word for.\n\n\t... Goes and looks ...\n\thttps://www.rfc-editor.org/rfc/rfc4880.html#section-7\n\tseems to use \"Armor Header and Armor Tail Lines\" to refer to\n\tthe BEGIN and the END delimiter lines, respectively.\n\nOther than that, the patch looks good to me.\n\nThanks.\n\n> +depending on signature type.\n> +\n> +PGP::\n> +\tSignatures begin with `-----BEGIN PGP SIGNATURE-----` and end\n> +\twith `-----END PGP SIGNATURE-----`, unless gpg is told to\n> +\tproduce RFC1991 signatures which use `MESSAGE` instead of\n> +\t`SIGNATURE`.\n> +\n> +SSH::\n> +\tSignatures begin with `-----BEGIN SSH SIGNATURE-----` and end\n> +\twith `-----END SSH SIGNATURE-----`.\n> +\n> +X.509::\n> +\tSignatures begin with `-----BEGIN SIGNED MESSAGE-----` and end\n> +\twith `-----END SIGNED MESSAGE-----`.\n> \n> Signatures sometimes appear as a part of the normal payload\n> (e.g. a signed tag has the signature block appended after the payload\n"},{"id":"446596","messageId":"xmqqzgnqgpbw.fsf@gitster.g","threadId":"57274","inReplyTo":"xmqq7daui4s8.fsf@gitster.g","subject":"Re: [PATCH] signature-format.txt: Note SSH and X.509 signature delimiters","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-01-20T19:49:23Z","receivedAt":"2022-01-20T19:49:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n>> +Signatures always begin and end with a delimiter, which differs\n>\n> The term \"signature delimiter\" is understandable, but is that the\n> term used by the users and the developers of OpenPGP, X.509 and SSH\n> who know and use such an ascii-armored signatures? Just making sure\n> we do not accidentally \"invent\" a new word that the upstream/wider\n> community has an established word for.\n>\n> \t... Goes and looks ...\n> \thttps://www.rfc-editor.org/rfc/rfc4880.html#section-7\n> \tseems to use \"Armor Header and Armor Tail Lines\" to refer to\n> \tthe BEGIN and the END delimiter lines, respectively.\n\nPlease do not take this as my recommendation to blindly adopt \"Armor\nHeader\" etc. It was merely an illustration of what level of due\ndiligence is expected behind a change in this project. If you make\na similar study of nomenclature used by X.509 and SSH folks, you may\ndiscover that there is no agreed-upon standard term common across\nthese three, in which case \"signature delimiter\" might be the best\n\"vendor neutral\" word to use in our documentation. Or it may turn\nout that RFC4880 is the oddball and the other two use the same words\nto refer to their header and tail lines, in which case, unless those\ncommon words are too technical and hard to understand for readers,\nwe may want to use that common one.\n\nThanks.\n\n"},{"id":"471892","messageId":"Y+XhPeh76D6/Uz6C@tilde.club","threadId":"57274","inReplyTo":"xmqq7daui4s8.fsf@gitster.g","subject":"Re: [PATCH] signature-format.txt: Note SSH and X.509 signature delimiters","fromName":"Gwyneth Morgan","fromEmail":"gwymor@tilde.club","sentAt":"2023-02-10T06:16:39Z","receivedAt":"2023-02-10T06:17:05Z","isPatch":true,"sender":{"key":"gwymor@tilde.club","avatar":"https://avatars.githubusercontent.com/u/87623694?v=4"},"body":"On 2022-01-20 11:30:15-0800, Junio C Hamano wrote:\n> Gwyneth Morgan writes:\n> > This document only explained PGP signatures, but Git now supports X.509\n> > and SSH signatures.\n> \n> This is technically incorrect as the original text does talk about\n> MESSAGE that is used by X.509.\n> \n> But the change does make it more clear to help readers not to make\n> the same mistake as the above sentence. In 3-item enumeration, it\n> is very clear what we now support ;-)\n\nI believe the existing language is referring to the\n\"-----BEGIN PGP MESSAGE-----\" format GPG outputs in RFC 1991 mode,\nrather than the \"-----BEGIN SIGNED MESSAGE-----\" that X.509 uses.\n\n> > diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt\n> > index 166721be6f..c148d4c750 100644\n> > --- a/Documentation/technical/signature-format.txt\n> > +++ b/Documentation/technical/signature-format.txt\n> > @@ -9,9 +9,22 @@ is about to create an object or transaction determines a payload from that,\n> > calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and\n> > embeds the signature into the object or transaction.\n> > \n> > -Signatures always begin with `-----BEGIN PGP SIGNATURE-----`\n> > -and end with `-----END PGP SIGNATURE-----`, unless gpg is told to\n> > -produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.\n> > +Signatures always begin and end with a delimiter, which differs\n> \n> The term \"signature delimiter\" is understandable, but is that the\n> term used by the users and the developers of OpenPGP, X.509 and SSH\n> who know and use such an ascii-armored signatures? Just making sure\n> we do not accidentally \"invent\" a new word that the upstream/wider\n> community has an established word for.\n> \n> \t... Goes and looks ...\n> \thttps://www.rfc-editor.org/rfc/rfc4880.html#section-7\n> \tseems to use \"Armor Header and Armor Tail Lines\" to refer to\n> \tthe BEGIN and the END delimiter lines, respectively.\n> \n> Other than that, the patch looks good to me.\n\nOpenSSH's signature format documentation says:\n\n\n\tThe Armored SSH signatures consist of a header, a base64\n\tencoded blob, and a footer.\n\n\tThe header is the string \"-----BEGIN SSH SIGNATURE-----\"\n\tfollowed by a newline. The footer is the string\n\t\"-----END SSH SIGNATURE-----\" immediately after a newline.\n(https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.sshsig?rev=1.4&content-type=text/x-cvsweb-markup)\n\nThis is sufficiently similar to the nomenclature in RFC 4880 to call\nthese \"Armor Header Line and Tail Line\" without any misunderstanding (or\n\"footer line\" if that's preferred). I did not find documentation on what\nX.509 calls these.\n"},{"id":"471893","messageId":"20230210061611.124932-1-gwymor@tilde.club","threadId":"57274","inReplyTo":"20220120053223.221667-1-gwymor@tilde.club","subject":"[PATCH v2] signature-format.txt: note SSH and X.509 signature delimiters","fromName":"Gwyneth Morgan","fromEmail":"gwymor@tilde.club","sentAt":"2023-02-10T06:16:11Z","receivedAt":"2023-02-10T06:18:15Z","isPatch":true,"sender":{"key":"gwymor@tilde.club","avatar":"https://avatars.githubusercontent.com/u/87623694?v=4"},"body":"This document only explained PGP signatures, but Git now supports X.509\nand SSH signatures.\n\nSigned-off-by: Gwyneth Morgan \n---\n Documentation/gitformat-signature.txt | 26 ++++++++++++++++++++------\n 1 file changed, 20 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt\nindex d8e3eb1bac..5f0c9202e3 100644\n--- a/Documentation/gitformat-signature.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -17,12 +17,26 @@ DESCRIPTION\n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n is about to create an object or transaction determines a payload from that,\n-calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and\n-embeds the signature into the object or transaction.\n-\n-Signatures always begin with `-----BEGIN PGP SIGNATURE-----`\n-and end with `-----END PGP SIGNATURE-----`, unless gpg is told to\n-produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.\n+calls an external program to obtain a detached signature for the payload\n+(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the\n+object or transaction.\n+\n+Signatures begin with an ASCII Armor header line and end with a tail line,\n+which differ depending on signature type.\n+\n+PGP::\n+\tSignatures begin with `-----BEGIN PGP SIGNATURE-----` and end\n+\twith `-----END PGP SIGNATURE-----`, unless gpg is told to\n+\tproduce RFC1991 signatures which use `MESSAGE` instead of\n+\t`SIGNATURE`.\n+\n+SSH::\n+\tSignatures begin with `-----BEGIN SSH SIGNATURE-----` and end\n+\twith `-----END SSH SIGNATURE-----`.\n+\n+X.509::\n+\tSignatures begin with `-----BEGIN SIGNED MESSAGE-----` and end\n+\twith `-----END SIGNED MESSAGE-----`.\n \n Signatures sometimes appear as a part of the normal payload\n (e.g. a signed tag has the signature block appended after the payload\n"},{"id":"471911","messageId":"230210.86ilg9wzho.gmgdl@evledraar.gmail.com","threadId":"57274","inReplyTo":"20230210061611.124932-1-gwymor@tilde.club","subject":"Re: [PATCH v2] signature-format.txt: note SSH and X.509 signature delimiters","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2023-02-10T10:52:42Z","receivedAt":"2023-02-10T11:07:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Feb 10 2023, Gwyneth Morgan wrote:\n\n> This document only explained PGP signatures, but Git now supports X.509\n> and SSH signatures.\n\nTo elaborate a bit, in 1e7adb97566 (gpg-interface: introduce new\nsignature format \"x509\" using gpgsm, 2018-07-17) we added X.509, and in\n29b315778e9 (ssh signing: add ssh key format and signing code,\n2021-09-10) we added \"ssh\", but our docs were never updated.\n\nYour commit message says as much in briefer terms, but maybe if you\nre-roll having those references would help put this change in context.>\n\n> Signed-off-by: Gwyneth Morgan \n> ---\n> Documentation/gitformat-signature.txt | 26 ++++++++++++++++++++------\n> 1 file changed, 20 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt\n> index d8e3eb1bac..5f0c9202e3 100644\n> --- a/Documentation/gitformat-signature.txt\n> +++ b/Documentation/gitformat-signature.txt\n> @@ -17,12 +17,26 @@ DESCRIPTION\n> Git uses cryptographic signatures in various places, currently objects (tags,\n> commits, mergetags) and transactions (pushes). In every case, the command which\n> is about to create an object or transaction determines a payload from that,\n> -calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and\n> -embeds the signature into the object or transaction.\n> -\n> -Signatures always begin with `-----BEGIN PGP SIGNATURE-----`\n> -and end with `-----END PGP SIGNATURE-----`, unless gpg is told to\n> -produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.\n> +calls an external program to obtain a detached signature for the payload\n> +(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the\n> +object or transaction.\n> +\n> +Signatures begin with an ASCII Armor header line and end with a tail line,\n> +which differ depending on signature type.\n\nDoes the \"ASCII Armor header\" really add something here, or just confuse\nthe user with a reference that's not followed-up or explained here?\nMaybe we should point out OpenPGP's '--armor' option in passing, to note\nto the reader that this isn't some git-specific concept.\n\n> +PGP::\n> +\tSignatures begin with `-----BEGIN PGP SIGNATURE-----` and end\n> +\twith `-----END PGP SIGNATURE-----`, unless gpg is told to\n> +\tproduce RFC1991 signatures which use `MESSAGE` instead of\n> +\t`SIGNATURE`.\n> +\n> +SSH::\n> +\tSignatures begin with `-----BEGIN SSH SIGNATURE-----` and end\n> +\twith `-----END SSH SIGNATURE-----`.\n> +\n> +X.509::\n> +\tSignatures begin with `-----BEGIN SIGNED MESSAGE-----` and end\n> +\twith `-----END SIGNED MESSAGE-----`.\n\nI wonder if structuring it like this wouldn't help make this easier to\nread, and reduce the repetition, as well as making the circular\nreferences between this & 'gpg.format' more obvious:\n\n\tThe signature start and end marker comes on its own line, and\n\tdiffers based on the signature type (as selected by\n\t'gpg.format', see linkgit:git-config[1]).\n\n Those are, for values of 'gpg.format':\n\n gpg: `-----BEGIN PGP SIGNATURE-----` and `-----END PGP\n SIGNATURE-----`. Or, if GPG has been asked to produce\n RFC1991 signatures: `-----BEGIN PGP MESSAGE-----` and\n `-----END PGP MESSAGE-----`\n\n x509: `-----BEGIN SIGNED MESSAGE-----` `-----END SIGNED MESSAGE-----`\n\tssh:`-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----`\n\nThen for gpg.format in Documentation/config/gpg.txt we could add e.g.:\n\n\tSee linkgit:gitformat-signature[5] for the signature format,\n\twhich differs based on the selected 'gpg.format'.\n"},{"id":"471925","messageId":"xmqqwn4pjw3c.fsf@gitster.g","threadId":"57274","inReplyTo":"Y+XhPeh76D6/Uz6C@tilde.club","subject":"Re: [PATCH] signature-format.txt: Note SSH and X.509 signature delimiters","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-10T16:58:47Z","receivedAt":"2023-02-10T16:59:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Gwyneth Morgan writes:\n\n> I believe the existing language is referring to the\n> \"-----BEGIN PGP MESSAGE-----\" format GPG outputs in RFC 1991 mode,\n> rather than the \"-----BEGIN SIGNED MESSAGE-----\" that X.509 uses.\n\nThe paragraph came from 76f9d8ba (Documentation/technical: describe\nsignature formats, 2016-06-17) that started the documentation, and\npredates x509 support by two years (and ssh came even later), so\nyou're right. It couldn't possibly have meant anything newer.\n\nThanks.\n\n> OpenSSH's signature format documentation says:\n>\n>\n> \tThe Armored SSH signatures consist of a header, a base64\n> \tencoded blob, and a footer.\n>\n> \tThe header is the string \"-----BEGIN SSH SIGNATURE-----\"\n> \tfollowed by a newline. The footer is the string\n> \t\"-----END SSH SIGNATURE-----\" immediately after a newline.\n>\n> This is sufficiently similar to the nomenclature in RFC 4880 to call\n> these \"Armor Header Line and Tail Line\" without any misunderstanding (or\n> \"footer line\" if that's preferred). I did not find documentation on what\n> X.509 calls these.\n\nSounds good. Thanks for due dilligence; it would make sure our\nnomenclature would not go out of line without a good reason.\n\n"},{"id":"471936","messageId":"xmqqfsbdiaqd.fsf@gitster.g","threadId":"57274","inReplyTo":"20230210061611.124932-1-gwymor@tilde.club","subject":"Re: [PATCH v2] signature-format.txt: note SSH and X.509 signature delimiters","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-10T19:25:30Z","receivedAt":"2023-02-10T19:25:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Gwyneth Morgan writes:\n\n> This document only explained PGP signatures, but Git now supports X.509\n> and SSH signatures.\n>\n> Signed-off-by: Gwyneth Morgan \n> ---\n> Documentation/gitformat-signature.txt | 26 ++++++++++++++++++++------\n> 1 file changed, 20 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt\n> index d8e3eb1bac..5f0c9202e3 100644\n> --- a/Documentation/gitformat-signature.txt\n> +++ b/Documentation/gitformat-signature.txt\n> @@ -17,12 +17,26 @@ DESCRIPTION\n> Git uses cryptographic signatures in various places, currently objects (tags,\n> commits, mergetags) and transactions (pushes). In every case, the command which\n> is about to create an object or transaction determines a payload from that,\n> +calls an external program to obtain a detached signature for the payload\n> +(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the\n> +object or transaction.\n> +\n> +Signatures begin with an ASCII Armor header line and end with a tail line,\n> +which differ depending on signature type.\n\nOK, we used to say \"begin with <>\" that was not\ngeneric, so we borrow the \"ascii armor header/tail line\" term the\ncrypto folks use. Then ...\n\n> +PGP::\n> +\tSignatures begin with `-----BEGIN PGP SIGNATURE-----` and end\n> +\twith `-----END PGP SIGNATURE-----`, unless gpg is told to\n\n... it may be easier to understand if the paragraph somehow made it\nclear that \"ascii armore header\" is \"-----BEGIN PGP SIGNATURE-----\"\nand \"tail\" is \"---END PGP SIGNATURE-----\" for the format being\ndescribed.\n\nAlternatively, if we are going to repeat \"... begin with X, and end\nwith Y\" for each format, then we may not even need to have the\nprevious paragraph that says these formats follow the same pattern\n(i.e. header then contents then tail, but header and tail are\ndifferent depending on the format).\n\n> +\tproduce RFC1991 signatures which use `MESSAGE` instead of\n> +\t`SIGNATURE`.\n> +\n> +SSH::\n> +\tSignatures begin with `-----BEGIN SSH SIGNATURE-----` and end\n> +\twith `-----END SSH SIGNATURE-----`.\n> +\n> +X.509::\n> +\tSignatures begin with `-----BEGIN SIGNED MESSAGE-----` and end\n> +\twith `-----END SIGNED MESSAGE-----`.\n"},{"id":"472821","messageId":"Y/0R3lDyJrtd4gIZ@tilde.club","threadId":"57274","inReplyTo":"230210.86ilg9wzho.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH v2] signature-format.txt: note SSH and X.509 signature delimiters","fromName":"Gwyneth Morgan","fromEmail":"gwymor@tilde.club","sentAt":"2023-02-27T20:26:06Z","receivedAt":"2023-02-27T20:26:30Z","isPatch":true,"sender":{"key":"gwymor@tilde.club","avatar":"https://avatars.githubusercontent.com/u/87623694?v=4"},"body":"On 2023-02-10 11:52:42+0100, Ævar Arnfjörð Bjarmason wrote:\n> \n> On Fri, Feb 10 2023, Gwyneth Morgan wrote:\n> \n> > This document only explained PGP signatures, but Git now supports X.509\n> > and SSH signatures.\n> \n> To elaborate a bit, in 1e7adb97566 (gpg-interface: introduce new\n> signature format \"x509\" using gpgsm, 2018-07-17) we added X.509, and in\n> 29b315778e9 (ssh signing: add ssh key format and signing code,\n> 2021-09-10) we added \"ssh\", but our docs were never updated.\n> \n> Your commit message says as much in briefer terms, but maybe if you\n> re-roll having those references would help put this change in context.>\n\nI'll reference those commits in v3.\n\n> > +Signatures begin with an ASCII Armor header line and end with a tail line,\n> > +which differ depending on signature type.\n> \n> Does the \"ASCII Armor header\" really add something here, or just confuse\n> the user with a reference that's not followed-up or explained here?\n> Maybe we should point out OpenPGP's '--armor' option in passing, to note\n> to the reader that this isn't some git-specific concept.\n\nI think having a relevant term to search for online and in manpages is\nhelpful. Mentioning the specific command-line option seems unnecessary,\nbut I'll put the term \"ASCII Armor\" in quotes to make it clearer that\nthis is not a git-specific concept.\n\n> I wonder if structuring it like this wouldn't help make this easier to\n> read, and reduce the repetition, as well as making the circular\n> references between this & 'gpg.format' more obvious:\n> \n> \tThe signature start and end marker comes on its own line, and\n> \tdiffers based on the signature type (as selected by\n> \t'gpg.format', see linkgit:git-config[1]).\n> \n> Those are, for values of 'gpg.format':\n> \n> gpg: `-----BEGIN PGP SIGNATURE-----` and `-----END PGP\n> SIGNATURE-----`. Or, if GPG has been asked to produce\n> RFC1991 signatures: `-----BEGIN PGP MESSAGE-----` and\n> `-----END PGP MESSAGE-----`\n> \n> x509: `-----BEGIN SIGNED MESSAGE-----` `-----END SIGNED MESSAGE-----`\n> \tssh:`-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----`\n\nLooks good. I'll do this in v3. I'll reference these by the gpg.format\nvalue, as well as a parenthetical proper name, like \"gpg (PGP)\"; these\nare basically the same the other two formats, but I want it to be clear\nthat `gpg` signatures don't have to be from the gpg program but could be\nfrom any PGP-supporting program.\n\n> Then for gpg.format in Documentation/config/gpg.txt we could add e.g.:\n> \n> \tSee linkgit:gitformat-signature[5] for the signature format,\n> \twhich differs based on the selected 'gpg.format'.\n\nOK.\n\nThanks.\n"},{"id":"472823","messageId":"20230227202718.173698-1-gwymor@tilde.club","threadId":"57274","inReplyTo":"20230210061611.124932-1-gwymor@tilde.club","subject":"[PATCH v3] signature-format.txt: note SSH and X.509 signature delimiters","fromName":"Gwyneth Morgan","fromEmail":"gwymor@tilde.club","sentAt":"2023-02-27T20:27:18Z","receivedAt":"2023-02-27T20:27:54Z","isPatch":true,"sender":{"key":"gwymor@tilde.club","avatar":"https://avatars.githubusercontent.com/u/87623694?v=4"},"body":"This document only explains PGP signatures, but Git now supports X.509\nsignatures as of 1e7adb9756 (gpg-interface: introduce new signature\nformat \"x509\" using gpgsm, 2018-07-17), and SSH signatures as of\n29b315778e (ssh signing: add ssh key format and signing code,\n2021-09-10).\n\nAdditionally, explain that these signature formats are controlled\n`gpg.format`, linking to its documentation, and explain in said\n`gpg.format` documentation that the underlying signature format is\ndocumented in signature-format.txt.\n\nSigned-off-by: Gwyneth Morgan \n---\n Documentation/config/gpg.txt | 3 +++\n Documentation/gitformat-signature.txt | 22 +++++++++++++++++-----\n 2 files changed, 20 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt\nindex 86f6308c4c..37e2831cd5 100644\n--- a/Documentation/config/gpg.txt\n+++ b/Documentation/config/gpg.txt\n@@ -12,6 +12,9 @@ gpg.program::\n gpg.format::\n \tSpecifies which key format to use when signing with `--gpg-sign`.\n \tDefault is \"openpgp\". Other possible values are \"x509\", \"ssh\".\n++\n+See linkgit:gitformat-signature[5] for the signature format, which differs\n+based on the selected `gpg.format`.\n \n gpg..program::\n \tUse this to customize the program used for the signing format you\ndiff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt\nindex d8e3eb1bac..d4d3a31f03 100644\n--- a/Documentation/gitformat-signature.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -17,12 +17,24 @@ DESCRIPTION\n Git uses cryptographic signatures in various places, currently objects (tags,\n commits, mergetags) and transactions (pushes). In every case, the command which\n is about to create an object or transaction determines a payload from that,\n-calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and\n-embeds the signature into the object or transaction.\n+calls an external program to obtain a detached signature for the payload\n+(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the\n+object or transaction.\n \n-Signatures always begin with `-----BEGIN PGP SIGNATURE-----`\n-and end with `-----END PGP SIGNATURE-----`, unless gpg is told to\n-produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.\n+Signatures begin with an \"ASCII Armor\" header line and end with a tail line,\n+which differ depending on signature type (as selected by `gpg.format`, see\n+linkgit:git-config[1]). These are, for `gpg.format` values:\n+\n+`gpg` (PGP)::\n+\t`-----BEGIN PGP SIGNATURE-----` and `-----END PGP SIGNATURE-----`.\n+\tOr, if gpg is told to produce RFC1991 signatures,\n+\t`-----BEGIN PGP MESSAGE-----` and `-----END PGP MESSAGE-----`\n+\n+`ssh` (SSH)::\n+\t`-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----`\n+\n+`x509` (X.509)::\n+\t`-----BEGIN SIGNED MESSAGE-----` and `-----END SIGNED MESSAGE-----`\n \n Signatures sometimes appear as a part of the normal payload\n (e.g. a signed tag has the signature block appended after the payload\n"},{"id":"472824","messageId":"xmqqa60ysrzq.fsf@gitster.g","threadId":"57274","inReplyTo":"20230227202718.173698-1-gwymor@tilde.club","subject":"Re: [PATCH v3] signature-format.txt: note SSH and X.509 signature delimiters","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-27T21:44:41Z","receivedAt":"2023-02-27T21:44:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Gwyneth Morgan writes:\n\n> This document only explains PGP signatures, but Git now supports X.509\n> signatures as of 1e7adb9756 (gpg-interface: introduce new signature\n> format \"x509\" using gpgsm, 2018-07-17), and SSH signatures as of\n> 29b315778e (ssh signing: add ssh key format and signing code,\n> 2021-09-10).\n>\n> Additionally, explain that these signature formats are controlled\n> `gpg.format`, linking to its documentation, and explain in said\n> `gpg.format` documentation that the underlying signature format is\n> documented in signature-format.txt.\n>\n> Signed-off-by: Gwyneth Morgan \n> ---\n> Documentation/config/gpg.txt | 3 +++\n> Documentation/gitformat-signature.txt | 22 +++++++++++++++++-----\n> 2 files changed, 20 insertions(+), 5 deletions(-)\n\nThanks, queued.\n"}]}