Documentation/gitformat-signature.txt

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