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