| Message ID | 20230210061611.124932-1-gwymor@tilde.club (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v2] signature-format.txt: note SSH and X.509 signature delimiters | expand |
On Fri, Feb 10 2023, Gwyneth Morgan wrote: > This document only explained PGP signatures, but Git now supports X.509 > and SSH signatures. To elaborate a bit, in 1e7adb97566 (gpg-interface: introduce new signature format "x509" using gpgsm, 2018-07-17) we added X.509, and in 29b315778e9 (ssh signing: add ssh key format and signing code, 2021-09-10) we added "ssh", but our docs were never updated. Your commit message says as much in briefer terms, but maybe if you re-roll having those references would help put this change in context.> > Signed-off-by: Gwyneth Morgan <gwymor@tilde.club> > --- > Documentation/gitformat-signature.txt | 26 ++++++++++++++++++++------ > 1 file changed, 20 insertions(+), 6 deletions(-) > > diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt > index d8e3eb1bac..5f0c9202e3 100644 > --- a/Documentation/gitformat-signature.txt > +++ b/Documentation/gitformat-signature.txt > @@ -17,12 +17,26 @@ DESCRIPTION > Git uses cryptographic signatures in various places, currently objects (tags, > commits, mergetags) and transactions (pushes). In every case, the command which > 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`. > +calls an external program to obtain a detached signature for the payload > +(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the > +object or transaction. > + > +Signatures begin with an ASCII Armor header line and end with a tail line, > +which differ depending on signature type. Does the "ASCII Armor header" really add something here, or just confuse the user with a reference that's not followed-up or explained here? Maybe we should point out OpenPGP's '--armor' option in passing, to note to the reader that this isn't some git-specific concept. > +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-----`. I wonder if structuring it like this wouldn't help make this easier to read, and reduce the repetition, as well as making the circular references between this & 'gpg.format' more obvious: The signature start and end marker comes on its own line, and differs based on the signature type (as selected by 'gpg.format', see linkgit:git-config[1]). Those are, for values of 'gpg.format': gpg: `-----BEGIN PGP SIGNATURE-----` and `-----END PGP SIGNATURE-----`. Or, if GPG has been asked to produce RFC1991 signatures: `-----BEGIN PGP MESSAGE-----` and `-----END PGP MESSAGE-----` x509: `-----BEGIN SIGNED MESSAGE-----` `-----END SIGNED MESSAGE-----` ssh:`-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----` Then for gpg.format in Documentation/config/gpg.txt we could add e.g.: See linkgit:gitformat-signature[5] for the signature format, which differs based on the selected 'gpg.format'.
Gwyneth Morgan <gwymor@tilde.club> writes: > This document only explained PGP signatures, but Git now supports X.509 > and SSH signatures. > > Signed-off-by: Gwyneth Morgan <gwymor@tilde.club> > --- > Documentation/gitformat-signature.txt | 26 ++++++++++++++++++++------ > 1 file changed, 20 insertions(+), 6 deletions(-) > > diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt > index d8e3eb1bac..5f0c9202e3 100644 > --- a/Documentation/gitformat-signature.txt > +++ b/Documentation/gitformat-signature.txt > @@ -17,12 +17,26 @@ DESCRIPTION > Git uses cryptographic signatures in various places, currently objects (tags, > commits, mergetags) and transactions (pushes). In every case, the command which > is about to create an object or transaction determines a payload from that, > +calls an external program to obtain a detached signature for the payload > +(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the > +object or transaction. > + > +Signatures begin with an ASCII Armor header line and end with a tail line, > +which differ depending on signature type. OK, we used to say "begin with <<something PGP>>" that was not generic, so we borrow the "ascii armor header/tail line" term the crypto folks use. Then ... > +PGP:: > + Signatures begin with `-----BEGIN PGP SIGNATURE-----` and end > + with `-----END PGP SIGNATURE-----`, unless gpg is told to ... it may be easier to understand if the paragraph somehow made it clear that "ascii armore header" is "-----BEGIN PGP SIGNATURE-----" and "tail" is "---END PGP SIGNATURE-----" for the format being described. Alternatively, if we are going to repeat "... begin with X, and end with Y" for each format, then we may not even need to have the previous paragraph that says these formats follow the same pattern (i.e. header then contents then tail, but header and tail are different depending on the format). > + 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-----`.
On 2023-02-10 11:52:42+0100, Ævar Arnfjörð Bjarmason wrote: > > On Fri, Feb 10 2023, Gwyneth Morgan wrote: > > > This document only explained PGP signatures, but Git now supports X.509 > > and SSH signatures. > > To elaborate a bit, in 1e7adb97566 (gpg-interface: introduce new > signature format "x509" using gpgsm, 2018-07-17) we added X.509, and in > 29b315778e9 (ssh signing: add ssh key format and signing code, > 2021-09-10) we added "ssh", but our docs were never updated. > > Your commit message says as much in briefer terms, but maybe if you > re-roll having those references would help put this change in context.> I'll reference those commits in v3. > > +Signatures begin with an ASCII Armor header line and end with a tail line, > > +which differ depending on signature type. > > Does the "ASCII Armor header" really add something here, or just confuse > the user with a reference that's not followed-up or explained here? > Maybe we should point out OpenPGP's '--armor' option in passing, to note > to the reader that this isn't some git-specific concept. I think having a relevant term to search for online and in manpages is helpful. Mentioning the specific command-line option seems unnecessary, but I'll put the term "ASCII Armor" in quotes to make it clearer that this is not a git-specific concept. > I wonder if structuring it like this wouldn't help make this easier to > read, and reduce the repetition, as well as making the circular > references between this & 'gpg.format' more obvious: > > The signature start and end marker comes on its own line, and > differs based on the signature type (as selected by > 'gpg.format', see linkgit:git-config[1]). > > Those are, for values of 'gpg.format': > > gpg: `-----BEGIN PGP SIGNATURE-----` and `-----END PGP > SIGNATURE-----`. Or, if GPG has been asked to produce > RFC1991 signatures: `-----BEGIN PGP MESSAGE-----` and > `-----END PGP MESSAGE-----` > > x509: `-----BEGIN SIGNED MESSAGE-----` `-----END SIGNED MESSAGE-----` > ssh:`-----BEGIN SSH SIGNATURE-----` and `-----END SSH SIGNATURE-----` Looks good. I'll do this in v3. I'll reference these by the gpg.format value, as well as a parenthetical proper name, like "gpg (PGP)"; these are basically the same the other two formats, but I want it to be clear that `gpg` signatures don't have to be from the gpg program but could be from any PGP-supporting program. > Then for gpg.format in Documentation/config/gpg.txt we could add e.g.: > > See linkgit:gitformat-signature[5] for the signature format, > which differs based on the selected 'gpg.format'. OK. Thanks.
diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt index d8e3eb1bac..5f0c9202e3 100644 --- a/Documentation/gitformat-signature.txt +++ b/Documentation/gitformat-signature.txt @@ -17,12 +17,26 @@ DESCRIPTION Git uses cryptographic signatures in various places, currently objects (tags, commits, mergetags) and transactions (pushes). In every case, the command which 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`. +calls an external program to obtain a detached signature for the payload +(`gpg -bsa` in the case of PGP signatures), and embeds the signature into the +object or transaction. + +Signatures begin with an ASCII Armor header line and end with a tail line, +which differ 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/gitformat-signature.txt | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-)