Documentation/technical/signature-format.txt

   1 Git signature format
   2 ====================
   3
   4 == Overview
   5
   6 Git uses cryptographic signatures in various places, currently objects (tags,
   7 commits, mergetags) and transactions (pushes). In every case, the command which
   8 is about to create an object or transaction determines a payload from that,
   9 calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and
  10 embeds the signature into the object or transaction.
  11
  12 Signatures always begin with `-----BEGIN PGP SIGNATURE-----`
  13 and end with `-----END PGP SIGNATURE-----`, unless gpg is told to
  14 produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.
  15
  16 Signatures sometimes appear as a part of the normal payload
  17 (e.g. a signed tag has the signature block appended after the payload
  18 that the signature applies to), and sometimes appear in the value of
  19 an object header (e.g. a merge commit that merged a signed tag would
  20 have the entire tag contents on its "mergetag" header).  In the case
  21 of the latter, the usual multi-line formatting rule for object
  22 headers applies.  I.e. the second and subsequent lines are prefixed
  23 with a SP to signal that the line is continued from the previous
  24 line.
  25
  26 This is even true for an originally empty line.  In the following
  27 examples, the end of line that ends with a whitespace letter is
  28 highlighted with a `$` sign; if you are trying to recreate these
  29 example by hand, do not cut and paste them---they are there
  30 primarily to highlight extra whitespace at the end of some lines.
  31
  32 The signed payload and the way the signature is embedded depends
  33 on the type of the object resp. transaction.
  34
  35 == Tag signatures
  36
  37 - created by: `git tag -s`
  38 - payload: annotated tag object
  39 - embedding: append the signature to the unsigned tag object
  40 - example: tag `signedtag` with subject `signed tag`
  41
  42 ----
  43 object 04b871796dc0420f8e7561a895b52484b701d51a
  44 type commit
  45 tag signedtag
  46 tagger C O Mitter <committer@example.com> 1465981006 +0000
  47
  48 signed tag
  49
  50 signed tag message body
  51 -----BEGIN PGP SIGNATURE-----
  52 Version: GnuPG v1
  53
  54 iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
  55 rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
  56 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
  57 q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
  58 rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
  59 lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
  60 =jpXa
  61 -----END PGP SIGNATURE-----
  62 ----
  63
  64 - verify with: `git verify-tag [-v]` or `git tag -v`
  65
  66 ----
  67 gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
  68 gpg: Good signature from "Eris Discordia <discord@example.net>"
  69 gpg: WARNING: This key is not certified with a trusted signature!
  70 gpg:          There is no indication that the signature belongs to the owner.
  71 Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
  72 object 04b871796dc0420f8e7561a895b52484b701d51a
  73 type commit
  74 tag signedtag
  75 tagger C O Mitter <committer@example.com> 1465981006 +0000
  76
  77 signed tag
  78
  79 signed tag message body
  80 ----
  81
  82 == Commit signatures
  83
  84 - created by: `git commit -S`
  85 - payload: commit object
  86 - embedding: header entry `gpgsig`
  87   (content is preceded by a space)
  88 - example: commit with subject `signed commit`
  89
  90 ----
  91 tree eebfed94e75e7760540d1485c740902590a00332
  92 parent 04b871796dc0420f8e7561a895b52484b701d51a
  93 author A U Thor <author@example.com> 1465981137 +0000
  94 committer C O Mitter <committer@example.com> 1465981137 +0000
  95 gpgsig -----BEGIN PGP SIGNATURE-----
  96  Version: GnuPG v1
  97  $
  98  iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
  99  HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
 100  DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA
 101  zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4
 102  HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1
 103  EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I=
 104  =jKHM
 105  -----END PGP SIGNATURE-----
 106
 107 signed commit
 108
 109 signed commit message body
 110 ----
 111
 112 - verify with: `git verify-commit [-v]` (or `git show --show-signature`)
 113
 114 ----
 115 gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189
 116 gpg: Good signature from "Eris Discordia <discord@example.net>"
 117 gpg: WARNING: This key is not certified with a trusted signature!
 118 gpg:          There is no indication that the signature belongs to the owner.
 119 Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 120 tree eebfed94e75e7760540d1485c740902590a00332
 121 parent 04b871796dc0420f8e7561a895b52484b701d51a
 122 author A U Thor <author@example.com> 1465981137 +0000
 123 committer C O Mitter <committer@example.com> 1465981137 +0000
 124
 125 signed commit
 126
 127 signed commit message body
 128 ----
 129
 130 == Mergetag signatures
 131
 132 - created by: `git merge` on signed tag
 133 - payload/embedding: the whole signed tag object is embedded into
 134   the (merge) commit object as header entry `mergetag`
 135 - example: merge of the signed tag `signedtag` as above
 136
 137 ----
 138 tree c7b1cff039a93f3600a1d18b82d26688668c7dea
 139 parent c33429be94b5f2d3ee9b0adad223f877f174b05d
 140 parent 04b871796dc0420f8e7561a895b52484b701d51a
 141 author A U Thor <author@example.com> 1465982009 +0000
 142 committer C O Mitter <committer@example.com> 1465982009 +0000
 143 mergetag object 04b871796dc0420f8e7561a895b52484b701d51a
 144  type commit
 145  tag signedtag
 146  tagger C O Mitter <committer@example.com> 1465981006 +0000
 147  $
 148  signed tag
 149  $
 150  signed tag message body
 151  -----BEGIN PGP SIGNATURE-----
 152  Version: GnuPG v1
 153  $
 154  iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
 155  rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
 156  8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
 157  q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
 158  rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
 159  lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
 160  =jpXa
 161  -----END PGP SIGNATURE-----
 162
 163 Merge tag 'signedtag' into downstream
 164
 165 signed tag
 166
 167 signed tag message body
 168
 169 # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
 170 # gpg: Good signature from "Eris Discordia <discord@example.net>"
 171 # gpg: WARNING: This key is not certified with a trusted signature!
 172 # gpg:          There is no indication that the signature belongs to the owner.
 173 # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 174 ----
 175
 176 - verify with: verification is embedded in merge commit message by default,
 177   alternatively with `git show --show-signature`:
 178
 179 ----
 180 commit 9863f0c76ff78712b6800e199a46aa56afbcbd49
 181 merged tag 'signedtag'
 182 gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
 183 gpg: Good signature from "Eris Discordia <discord@example.net>"
 184 gpg: WARNING: This key is not certified with a trusted signature!
 185 gpg:          There is no indication that the signature belongs to the owner.
 186 Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 187 Merge: c33429b 04b8717
 188 Author: A U Thor <author@example.com>
 189 Date:   Wed Jun 15 09:13:29 2016 +0000
 190
 191     Merge tag 'signedtag' into downstream
 192
 193     signed tag
 194
 195     signed tag message body
 196
 197     # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
 198     # gpg: Good signature from "Eris Discordia <discord@example.net>"
 199     # gpg: WARNING: This key is not certified with a trusted signature!
 200     # gpg:          There is no indication that the signature belongs to the owner.
 201     # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 202 ----