man5/gitformat-signature.5

   1 '\" t
   2 .\"     Title: gitformat-signature
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-06-01
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.41.0
   8 .\"  Language: English
   9 .\"
  10 .TH "GITFORMAT\-SIGNATURE" "5" "2023\-06\-01" "Git 2\&.41\&.0" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 gitformat-signature \- Git cryptographic signature formats
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 <[tag|commit] object header(s)>
  36 <over\-the\-wire protocol>
  37 .fi
  38 .sp
  39 .SH "DESCRIPTION"
  40 .sp
  41 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 (\fBgpg \-bsa\fR in the case of PGP signatures), and embeds the signature into the object or transaction\&.
  42 .sp
  43 Signatures begin with an "ASCII Armor" header line and end with a tail line, which differ depending on signature type (as selected by \fBgpg\&.format\fR, see \fBgit-config\fR(1))\&. These are, for \fBgpg\&.format\fR values:
  44 .PP
  45 \fBgpg\fR (PGP)
  46 .RS 4
  47 \fB\-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-\fR
  48 and
  49 \fB\-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-\fR\&. Or, if gpg is told to produce RFC1991 signatures,
  50 \fB\-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\-\fR
  51 and
  52 \fB\-\-\-\-\-END PGP MESSAGE\-\-\-\-\-\fR
  53 .RE
  54 .PP
  55 \fBssh\fR (SSH)
  56 .RS 4
  57 \fB\-\-\-\-\-BEGIN SSH SIGNATURE\-\-\-\-\-\fR
  58 and
  59 \fB\-\-\-\-\-END SSH SIGNATURE\-\-\-\-\-\fR
  60 .RE
  61 .PP
  62 \fBx509\fR (X\&.509)
  63 .RS 4
  64 \fB\-\-\-\-\-BEGIN SIGNED MESSAGE\-\-\-\-\-\fR
  65 and
  66 \fB\-\-\-\-\-END SIGNED MESSAGE\-\-\-\-\-\fR
  67 .RE
  68 .sp
  69 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\&.
  70 .sp
  71 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 \fB$\fR sign; if you are trying to recreate these example by hand, do not cut and paste them\(emthey are there primarily to highlight extra whitespace at the end of some lines\&.
  72 .sp
  73 The signed payload and the way the signature is embedded depends on the type of the object resp\&. transaction\&.
  74 .SH "TAG SIGNATURES"
  75 .sp
  76 .RS 4
  77 .ie n \{\
  78 \h'-04'\(bu\h'+03'\c
  79 .\}
  80 .el \{\
  81 .sp -1
  82 .IP \(bu 2.3
  83 .\}
  84 created by:
  85 \fBgit tag \-s\fR
  86 .RE
  87 .sp
  88 .RS 4
  89 .ie n \{\
  90 \h'-04'\(bu\h'+03'\c
  91 .\}
  92 .el \{\
  93 .sp -1
  94 .IP \(bu 2.3
  95 .\}
  96 payload: annotated tag object
  97 .RE
  98 .sp
  99 .RS 4
 100 .ie n \{\
 101 \h'-04'\(bu\h'+03'\c
 102 .\}
 103 .el \{\
 104 .sp -1
 105 .IP \(bu 2.3
 106 .\}
 107 embedding: append the signature to the unsigned tag object
 108 .RE
 109 .sp
 110 .RS 4
 111 .ie n \{\
 112 \h'-04'\(bu\h'+03'\c
 113 .\}
 114 .el \{\
 115 .sp -1
 116 .IP \(bu 2.3
 117 .\}
 118 example: tag
 119 \fBsignedtag\fR
 120 with subject
 121 \fBsigned tag\fR
 122 .RE
 123 .sp
 124 .if n \{\
 125 .RS 4
 126 .\}
 127 .nf
 128 object 04b871796dc0420f8e7561a895b52484b701d51a
 129 type commit
 130 tag signedtag
 131 tagger C O Mitter <committer@example\&.com> 1465981006 +0000
 132
 133 signed tag
 134
 135 signed tag message body
 136 \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
 137 Version: GnuPG v1
 138
 139 iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
 140 rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
 141 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
 142 q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
 143 rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
 144 lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
 145 =jpXa
 146 \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
 147 .fi
 148 .if n \{\
 149 .RE
 150 .\}
 151 .sp
 152
 153 .sp
 154 .RS 4
 155 .ie n \{\
 156 \h'-04'\(bu\h'+03'\c
 157 .\}
 158 .el \{\
 159 .sp -1
 160 .IP \(bu 2.3
 161 .\}
 162 verify with:
 163 \fBgit verify\-tag [\-v]\fR
 164 or
 165 \fBgit tag \-v\fR
 166 .RE
 167 .sp
 168 .if n \{\
 169 .RS 4
 170 .\}
 171 .nf
 172 gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
 173 gpg: Good signature from "Eris Discordia <discord@example\&.net>"
 174 gpg: WARNING: This key is not certified with a trusted signature!
 175 gpg:          There is no indication that the signature belongs to the owner\&.
 176 Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 177 object 04b871796dc0420f8e7561a895b52484b701d51a
 178 type commit
 179 tag signedtag
 180 tagger C O Mitter <committer@example\&.com> 1465981006 +0000
 181
 182 signed tag
 183
 184 signed tag message body
 185 .fi
 186 .if n \{\
 187 .RE
 188 .\}
 189 .sp
 190 .SH "COMMIT SIGNATURES"
 191 .sp
 192 .RS 4
 193 .ie n \{\
 194 \h'-04'\(bu\h'+03'\c
 195 .\}
 196 .el \{\
 197 .sp -1
 198 .IP \(bu 2.3
 199 .\}
 200 created by:
 201 \fBgit commit \-S\fR
 202 .RE
 203 .sp
 204 .RS 4
 205 .ie n \{\
 206 \h'-04'\(bu\h'+03'\c
 207 .\}
 208 .el \{\
 209 .sp -1
 210 .IP \(bu 2.3
 211 .\}
 212 payload: commit object
 213 .RE
 214 .sp
 215 .RS 4
 216 .ie n \{\
 217 \h'-04'\(bu\h'+03'\c
 218 .\}
 219 .el \{\
 220 .sp -1
 221 .IP \(bu 2.3
 222 .\}
 223 embedding: header entry
 224 \fBgpgsig\fR
 225 (content is preceded by a space)
 226 .RE
 227 .sp
 228 .RS 4
 229 .ie n \{\
 230 \h'-04'\(bu\h'+03'\c
 231 .\}
 232 .el \{\
 233 .sp -1
 234 .IP \(bu 2.3
 235 .\}
 236 example: commit with subject
 237 \fBsigned commit\fR
 238 .RE
 239 .sp
 240 .if n \{\
 241 .RS 4
 242 .\}
 243 .nf
 244 tree eebfed94e75e7760540d1485c740902590a00332
 245 parent 04b871796dc0420f8e7561a895b52484b701d51a
 246 author A U Thor <author@example\&.com> 1465981137 +0000
 247 committer C O Mitter <committer@example\&.com> 1465981137 +0000
 248 gpgsig \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
 249  Version: GnuPG v1
 250  $
 251  iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
 252  HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
 253  DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA
 254  zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4
 255  HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1
 256  EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I=
 257  =jKHM
 258  \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
 259
 260 signed commit
 261
 262 signed commit message body
 263 .fi
 264 .if n \{\
 265 .RE
 266 .\}
 267 .sp
 268
 269 .sp
 270 .RS 4
 271 .ie n \{\
 272 \h'-04'\(bu\h'+03'\c
 273 .\}
 274 .el \{\
 275 .sp -1
 276 .IP \(bu 2.3
 277 .\}
 278 verify with:
 279 \fBgit verify\-commit [\-v]\fR
 280 (or
 281 \fBgit show \-\-show\-signature\fR)
 282 .RE
 283 .sp
 284 .if n \{\
 285 .RS 4
 286 .\}
 287 .nf
 288 gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189
 289 gpg: Good signature from "Eris Discordia <discord@example\&.net>"
 290 gpg: WARNING: This key is not certified with a trusted signature!
 291 gpg:          There is no indication that the signature belongs to the owner\&.
 292 Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 293 tree eebfed94e75e7760540d1485c740902590a00332
 294 parent 04b871796dc0420f8e7561a895b52484b701d51a
 295 author A U Thor <author@example\&.com> 1465981137 +0000
 296 committer C O Mitter <committer@example\&.com> 1465981137 +0000
 297
 298 signed commit
 299
 300 signed commit message body
 301 .fi
 302 .if n \{\
 303 .RE
 304 .\}
 305 .sp
 306 .SH "MERGETAG SIGNATURES"
 307 .sp
 308 .RS 4
 309 .ie n \{\
 310 \h'-04'\(bu\h'+03'\c
 311 .\}
 312 .el \{\
 313 .sp -1
 314 .IP \(bu 2.3
 315 .\}
 316 created by:
 317 \fBgit merge\fR
 318 on signed tag
 319 .RE
 320 .sp
 321 .RS 4
 322 .ie n \{\
 323 \h'-04'\(bu\h'+03'\c
 324 .\}
 325 .el \{\
 326 .sp -1
 327 .IP \(bu 2.3
 328 .\}
 329 payload/embedding: the whole signed tag object is embedded into the (merge) commit object as header entry
 330 \fBmergetag\fR
 331 .RE
 332 .sp
 333 .RS 4
 334 .ie n \{\
 335 \h'-04'\(bu\h'+03'\c
 336 .\}
 337 .el \{\
 338 .sp -1
 339 .IP \(bu 2.3
 340 .\}
 341 example: merge of the signed tag
 342 \fBsignedtag\fR
 343 as above
 344 .RE
 345 .sp
 346 .if n \{\
 347 .RS 4
 348 .\}
 349 .nf
 350 tree c7b1cff039a93f3600a1d18b82d26688668c7dea
 351 parent c33429be94b5f2d3ee9b0adad223f877f174b05d
 352 parent 04b871796dc0420f8e7561a895b52484b701d51a
 353 author A U Thor <author@example\&.com> 1465982009 +0000
 354 committer C O Mitter <committer@example\&.com> 1465982009 +0000
 355 mergetag object 04b871796dc0420f8e7561a895b52484b701d51a
 356  type commit
 357  tag signedtag
 358  tagger C O Mitter <committer@example\&.com> 1465981006 +0000
 359  $
 360  signed tag
 361  $
 362  signed tag message body
 363  \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
 364  Version: GnuPG v1
 365  $
 366  iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
 367  rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
 368  8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
 369  q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
 370  rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
 371  lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
 372  =jpXa
 373  \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
 374
 375 Merge tag \*(Aqsignedtag\*(Aq into downstream
 376
 377 signed tag
 378
 379 signed tag message body
 380
 381 # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
 382 # gpg: Good signature from "Eris Discordia <discord@example\&.net>"
 383 # gpg: WARNING: This key is not certified with a trusted signature!
 384 # gpg:          There is no indication that the signature belongs to the owner\&.
 385 # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 386 .fi
 387 .if n \{\
 388 .RE
 389 .\}
 390 .sp
 391
 392 .sp
 393 .RS 4
 394 .ie n \{\
 395 \h'-04'\(bu\h'+03'\c
 396 .\}
 397 .el \{\
 398 .sp -1
 399 .IP \(bu 2.3
 400 .\}
 401 verify with: verification is embedded in merge commit message by default, alternatively with
 402 \fBgit show \-\-show\-signature\fR:
 403 .RE
 404 .sp
 405 .if n \{\
 406 .RS 4
 407 .\}
 408 .nf
 409 commit 9863f0c76ff78712b6800e199a46aa56afbcbd49
 410 merged tag \*(Aqsignedtag\*(Aq
 411 gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
 412 gpg: Good signature from "Eris Discordia <discord@example\&.net>"
 413 gpg: WARNING: This key is not certified with a trusted signature!
 414 gpg:          There is no indication that the signature belongs to the owner\&.
 415 Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 416 Merge: c33429b 04b8717
 417 Author: A U Thor <author@example\&.com>
 418 Date:   Wed Jun 15 09:13:29 2016 +0000
 419
 420     Merge tag \*(Aqsignedtag\*(Aq into downstream
 421
 422     signed tag
 423
 424     signed tag message body
 425
 426     # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
 427     # gpg: Good signature from "Eris Discordia <discord@example\&.net>"
 428     # gpg: WARNING: This key is not certified with a trusted signature!
 429     # gpg:          There is no indication that the signature belongs to the owner\&.
 430     # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
 431 .fi
 432 .if n \{\
 433 .RE
 434 .\}
 435 .sp
 436 .SH "GIT"
 437 .sp
 438 Part of the \fBgit\fR(1) suite