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