path: root/man5/gitformat-signature.5

'\" t
.\"     Title: gitformat-signature
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-24
.\"    Manual: Git Manual
.\"    Source: Git 2.45.0.rc1.1.g9f32d8da7a
.\"  Language: English
.\"
.TH "GITFORMAT\-SIGNATURE" "5" "2024\-04\-24" "Git 2\&.45\&.0\&.rc1\&.1\&.g9f" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gitformat-signature \- Git cryptographic signature formats
.SH "SYNOPSIS"
.sp
.nf
<[tag|commit] object header(s)>
<over\-the\-wire protocol>
.fi
.sp
.SH "DESCRIPTION"
.sp
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\&.
.sp
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:
.PP
\fBgpg\fR (PGP)
.RS 4
\fB\-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-\fR
and
\fB\-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-\fR\&. Or, if gpg is told to produce RFC1991 signatures,
\fB\-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\-\fR
and
\fB\-\-\-\-\-END PGP MESSAGE\-\-\-\-\-\fR
.RE
.PP
\fBssh\fR (SSH)
.RS 4
\fB\-\-\-\-\-BEGIN SSH SIGNATURE\-\-\-\-\-\fR
and
\fB\-\-\-\-\-END SSH SIGNATURE\-\-\-\-\-\fR
.RE
.PP
\fBx509\fR (X\&.509)
.RS 4
\fB\-\-\-\-\-BEGIN SIGNED MESSAGE\-\-\-\-\-\fR
and
\fB\-\-\-\-\-END SIGNED MESSAGE\-\-\-\-\-\fR
.RE
.sp
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\&.
.sp
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\&.
.sp
The signed payload and the way the signature is embedded depends on the type of the object resp\&. transaction\&.
.SH "TAG SIGNATURES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
created by:
\fBgit tag \-s\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
payload: annotated tag object
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
embedding: append the signature to the unsigned tag object
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example: tag
\fBsignedtag\fR
with subject
\fBsigned tag\fR
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
object 04b871796dc0420f8e7561a895b52484b701d51a
type commit
tag signedtag
tagger C O Mitter <committer@example\&.com> 1465981006 +0000

signed tag

signed tag message body
\-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
Version: GnuPG v1

iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
=jpXa
\-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
.fi
.if n \{\
.RE
.\}
.sp

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
verify with:
\fBgit verify\-tag [\-v]\fR
or
\fBgit tag \-v\fR
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
gpg: Good signature from "Eris Discordia <discord@example\&.net>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner\&.
Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
object 04b871796dc0420f8e7561a895b52484b701d51a
type commit
tag signedtag
tagger C O Mitter <committer@example\&.com> 1465981006 +0000

signed tag

signed tag message body
.fi
.if n \{\
.RE
.\}
.sp
.SH "COMMIT SIGNATURES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
created by:
\fBgit commit \-S\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
payload: commit object
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
embedding: header entry
\fBgpgsig\fR
(content is preceded by a space)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example: commit with subject
\fBsigned commit\fR
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
tree eebfed94e75e7760540d1485c740902590a00332
parent 04b871796dc0420f8e7561a895b52484b701d51a
author A U Thor <author@example\&.com> 1465981137 +0000
committer C O Mitter <committer@example\&.com> 1465981137 +0000
gpgsig \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
 Version: GnuPG v1
 $
 iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
 HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
 DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA
 zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4
 HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1
 EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I=
 =jKHM
 \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-

signed commit

signed commit message body
.fi
.if n \{\
.RE
.\}
.sp

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
verify with:
\fBgit verify\-commit [\-v]\fR
(or
\fBgit show \-\-show\-signature\fR)
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189
gpg: Good signature from "Eris Discordia <discord@example\&.net>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner\&.
Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
tree eebfed94e75e7760540d1485c740902590a00332
parent 04b871796dc0420f8e7561a895b52484b701d51a
author A U Thor <author@example\&.com> 1465981137 +0000
committer C O Mitter <committer@example\&.com> 1465981137 +0000

signed commit

signed commit message body
.fi
.if n \{\
.RE
.\}
.sp
.SH "MERGETAG SIGNATURES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
created by:
\fBgit merge\fR
on signed tag
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
payload/embedding: the whole signed tag object is embedded into the (merge) commit object as header entry
\fBmergetag\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
example: merge of the signed tag
\fBsignedtag\fR
as above
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
tree c7b1cff039a93f3600a1d18b82d26688668c7dea
parent c33429be94b5f2d3ee9b0adad223f877f174b05d
parent 04b871796dc0420f8e7561a895b52484b701d51a
author A U Thor <author@example\&.com> 1465982009 +0000
committer C O Mitter <committer@example\&.com> 1465982009 +0000
mergetag object 04b871796dc0420f8e7561a895b52484b701d51a
 type commit
 tag signedtag
 tagger C O Mitter <committer@example\&.com> 1465981006 +0000
 $
 signed tag
 $
 signed tag message body
 \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
 Version: GnuPG v1
 $
 iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
 rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
 q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
 rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
 lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
 =jpXa
 \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-

Merge tag \*(Aqsignedtag\*(Aq into downstream

signed tag

signed tag message body

# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
# gpg: Good signature from "Eris Discordia <discord@example\&.net>"
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg:          There is no indication that the signature belongs to the owner\&.
# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
.fi
.if n \{\
.RE
.\}
.sp

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
verify with: verification is embedded in merge commit message by default, alternatively with
\fBgit show \-\-show\-signature\fR:
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
commit 9863f0c76ff78712b6800e199a46aa56afbcbd49
merged tag \*(Aqsignedtag\*(Aq
gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
gpg: Good signature from "Eris Discordia <discord@example\&.net>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner\&.
Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
Merge: c33429b 04b8717
Author: A U Thor <author@example\&.com>
Date:   Wed Jun 15 09:13:29 2016 +0000

    Merge tag \*(Aqsignedtag\*(Aq into downstream

    signed tag

    signed tag message body

    # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
    # gpg: Good signature from "Eris Discordia <discord@example\&.net>"
    # gpg: WARNING: This key is not certified with a trusted signature!
    # gpg:          There is no indication that the signature belongs to the owner\&.
    # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
.fi
.if n \{\
.RE
.\}
.sp
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite