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