From 20516890dc86c2949419287d59b4f3df7e7972e0 Mon Sep 17 00:00:00 2001 From: Ævar Arnfjörð Bjarmason Date: Thu, 4 Aug 2022 18:28:38 +0200 Subject: docs: move signature docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the signature format documentation. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- Documentation/gitformat-signature.txt | 217 +++++++++++++++++++++++++++ Documentation/technical/signature-format.txt | 202 ------------------------- command-list.txt | 1 + 4 files changed, 219 insertions(+), 203 deletions(-) create mode 100644 Documentation/gitformat-signature.txt delete mode 100644 Documentation/technical/signature-format.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 029067a77d..d122d1751d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -27,6 +27,7 @@ MAN5_TXT += gitattributes.txt MAN5_TXT += gitformat-bundle.txt MAN5_TXT += gitformat-commit-graph.txt MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt MAN5_TXT += gitmailmap.txt @@ -115,7 +116,6 @@ TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow -TECH_DOCS += technical/signature-format TECH_DOCS += technical/trivial-merge SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt new file mode 100644 index 0000000000..a249869faf --- /dev/null +++ b/Documentation/gitformat-signature.txt @@ -0,0 +1,217 @@ +gitformat-signature(5) +====================== + +NAME +---- +gitformat-signature - Git cryptographic signature formats + +SYNOPSIS +-------- +[verse] +<[tag|commit] object header(s)> + + +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`. + +Signatures sometimes appear as a part of the normal payload +(e.g. a signed tag has the signature block appended after the payload +that the signature applies to), and sometimes appear in the value of +an object header (e.g. a merge commit that merged a signed tag would +have the entire tag contents on its "mergetag" header). In the case +of the latter, the usual multi-line formatting rule for object +headers applies. I.e. the second and subsequent lines are prefixed +with a SP to signal that the line is continued from the previous +line. + +This is even true for an originally empty line. In the following +examples, the end of line that ends with a whitespace letter is +highlighted with a `$` sign; if you are trying to recreate these +example by hand, do not cut and paste them---they are there +primarily to highlight extra whitespace at the end of some lines. + +The signed payload and the way the signature is embedded depends +on the type of the object resp. transaction. + +== Tag signatures + +- created by: `git tag -s` +- payload: annotated tag object +- embedding: append the signature to the unsigned tag object +- example: tag `signedtag` with subject `signed tag` + +---- +object 04b871796dc0420f8e7561a895b52484b701d51a +type commit +tag signedtag +tagger C O Mitter 1465981006 +0000 + +signed tag + +signed tag message body +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v1 + +iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn +rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh +8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods +q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 +rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x +lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= +=jpXa +-----END PGP SIGNATURE----- +---- + +- verify with: `git verify-tag [-v]` or `git tag -v` + +---- +gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia " +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +object 04b871796dc0420f8e7561a895b52484b701d51a +type commit +tag signedtag +tagger C O Mitter 1465981006 +0000 + +signed tag + +signed tag message body +---- + +== Commit signatures + +- created by: `git commit -S` +- payload: commit object +- embedding: header entry `gpgsig` + (content is preceded by a space) +- example: commit with subject `signed commit` + +---- +tree eebfed94e75e7760540d1485c740902590a00332 +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor 1465981137 +0000 +committer C O Mitter 1465981137 +0000 +gpgsig -----BEGIN PGP SIGNATURE----- + Version: GnuPG v1 + $ + iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/ + HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7 + DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA + zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4 + HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1 + EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I= + =jKHM + -----END PGP SIGNATURE----- + +signed commit + +signed commit message body +---- + +- verify with: `git verify-commit [-v]` (or `git show --show-signature`) + +---- +gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia " +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +tree eebfed94e75e7760540d1485c740902590a00332 +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor 1465981137 +0000 +committer C O Mitter 1465981137 +0000 + +signed commit + +signed commit message body +---- + +== Mergetag signatures + +- created by: `git merge` on signed tag +- payload/embedding: the whole signed tag object is embedded into + the (merge) commit object as header entry `mergetag` +- example: merge of the signed tag `signedtag` as above + +---- +tree c7b1cff039a93f3600a1d18b82d26688668c7dea +parent c33429be94b5f2d3ee9b0adad223f877f174b05d +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor 1465982009 +0000 +committer C O Mitter 1465982009 +0000 +mergetag object 04b871796dc0420f8e7561a895b52484b701d51a + type commit + tag signedtag + tagger C O Mitter 1465981006 +0000 + $ + signed tag + $ + signed tag message body + -----BEGIN PGP SIGNATURE----- + Version: GnuPG v1 + $ + iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn + rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh + 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods + q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 + rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x + lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= + =jpXa + -----END PGP SIGNATURE----- + +Merge tag 'signedtag' into downstream + +signed tag + +signed tag message body + +# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 +# gpg: Good signature from "Eris Discordia " +# gpg: WARNING: This key is not certified with a trusted signature! +# gpg: There is no indication that the signature belongs to the owner. +# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +---- + +- verify with: verification is embedded in merge commit message by default, + alternatively with `git show --show-signature`: + +---- +commit 9863f0c76ff78712b6800e199a46aa56afbcbd49 +merged tag 'signedtag' +gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia " +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +Merge: c33429b 04b8717 +Author: A U Thor +Date: Wed Jun 15 09:13:29 2016 +0000 + + Merge tag 'signedtag' into downstream + + signed tag + + signed tag message body + + # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 + # gpg: Good signature from "Eris Discordia " + # gpg: WARNING: This key is not certified with a trusted signature! + # gpg: There is no indication that the signature belongs to the owner. + # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +---- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt deleted file mode 100644 index 166721be6f..0000000000 --- a/Documentation/technical/signature-format.txt +++ /dev/null @@ -1,202 +0,0 @@ -Git signature format -==================== - -== Overview - -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`. - -Signatures sometimes appear as a part of the normal payload -(e.g. a signed tag has the signature block appended after the payload -that the signature applies to), and sometimes appear in the value of -an object header (e.g. a merge commit that merged a signed tag would -have the entire tag contents on its "mergetag" header). In the case -of the latter, the usual multi-line formatting rule for object -headers applies. I.e. the second and subsequent lines are prefixed -with a SP to signal that the line is continued from the previous -line. - -This is even true for an originally empty line. In the following -examples, the end of line that ends with a whitespace letter is -highlighted with a `$` sign; if you are trying to recreate these -example by hand, do not cut and paste them---they are there -primarily to highlight extra whitespace at the end of some lines. - -The signed payload and the way the signature is embedded depends -on the type of the object resp. transaction. - -== Tag signatures - -- created by: `git tag -s` -- payload: annotated tag object -- embedding: append the signature to the unsigned tag object -- example: tag `signedtag` with subject `signed tag` - ----- -object 04b871796dc0420f8e7561a895b52484b701d51a -type commit -tag signedtag -tagger C O Mitter 1465981006 +0000 - -signed tag - -signed tag message body ------BEGIN PGP SIGNATURE----- -Version: GnuPG v1 - -iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn -rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh -8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods -q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 -rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x -lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= -=jpXa ------END PGP SIGNATURE----- ----- - -- verify with: `git verify-tag [-v]` or `git tag -v` - ----- -gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 -gpg: Good signature from "Eris Discordia " -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 -object 04b871796dc0420f8e7561a895b52484b701d51a -type commit -tag signedtag -tagger C O Mitter 1465981006 +0000 - -signed tag - -signed tag message body ----- - -== Commit signatures - -- created by: `git commit -S` -- payload: commit object -- embedding: header entry `gpgsig` - (content is preceded by a space) -- example: commit with subject `signed commit` - ----- -tree eebfed94e75e7760540d1485c740902590a00332 -parent 04b871796dc0420f8e7561a895b52484b701d51a -author A U Thor 1465981137 +0000 -committer C O Mitter 1465981137 +0000 -gpgsig -----BEGIN PGP SIGNATURE----- - Version: GnuPG v1 - $ - iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/ - HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7 - DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA - zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4 - HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1 - EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I= - =jKHM - -----END PGP SIGNATURE----- - -signed commit - -signed commit message body ----- - -- verify with: `git verify-commit [-v]` (or `git show --show-signature`) - ----- -gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189 -gpg: Good signature from "Eris Discordia " -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 -tree eebfed94e75e7760540d1485c740902590a00332 -parent 04b871796dc0420f8e7561a895b52484b701d51a -author A U Thor 1465981137 +0000 -committer C O Mitter 1465981137 +0000 - -signed commit - -signed commit message body ----- - -== Mergetag signatures - -- created by: `git merge` on signed tag -- payload/embedding: the whole signed tag object is embedded into - the (merge) commit object as header entry `mergetag` -- example: merge of the signed tag `signedtag` as above - ----- -tree c7b1cff039a93f3600a1d18b82d26688668c7dea -parent c33429be94b5f2d3ee9b0adad223f877f174b05d -parent 04b871796dc0420f8e7561a895b52484b701d51a -author A U Thor 1465982009 +0000 -committer C O Mitter 1465982009 +0000 -mergetag object 04b871796dc0420f8e7561a895b52484b701d51a - type commit - tag signedtag - tagger C O Mitter 1465981006 +0000 - $ - signed tag - $ - signed tag message body - -----BEGIN PGP SIGNATURE----- - Version: GnuPG v1 - $ - iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn - rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh - 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods - q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 - rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x - lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= - =jpXa - -----END PGP SIGNATURE----- - -Merge tag 'signedtag' into downstream - -signed tag - -signed tag message body - -# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 -# gpg: Good signature from "Eris Discordia " -# gpg: WARNING: This key is not certified with a trusted signature! -# gpg: There is no indication that the signature belongs to the owner. -# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 ----- - -- verify with: verification is embedded in merge commit message by default, - alternatively with `git show --show-signature`: - ----- -commit 9863f0c76ff78712b6800e199a46aa56afbcbd49 -merged tag 'signedtag' -gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 -gpg: Good signature from "Eris Discordia " -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 -Merge: c33429b 04b8717 -Author: A U Thor -Date: Wed Jun 15 09:13:29 2016 +0000 - - Merge tag 'signedtag' into downstream - - signed tag - - signed tag message body - - # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 - # gpg: Good signature from "Eris Discordia " - # gpg: WARNING: This key is not certified with a trusted signature! - # gpg: There is no indication that the signature belongs to the owner. - # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 ----- diff --git a/command-list.txt b/command-list.txt index 5e8d838668..68212e3c1b 100644 --- a/command-list.txt +++ b/command-list.txt @@ -212,6 +212,7 @@ gitfaq guide gitformat-bundle developerinterfaces gitformat-commit-graph developerinterfaces gitformat-index developerinterfaces +gitformat-signature developerinterfaces gitglossary guide githooks userinterfaces gitignore userinterfaces -- cgit v1.3-5-g9baa