.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DPKG-SIG 1"
.TH DPKG-SIG 1 "2016-12-19" "Debian Project" "Debian GNU/Linux manual"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dpkg\-sig \- Debian package archive (.deb) signature generation and verification tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-sign\fR \fIrole\fR \fI[archive|changes]\fR+
.PP
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-verify\fR \fI[archive]\fR+
.PP
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-verify\-role\fR \fIrole\fR \fI[archive]\fR+
.PP
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-verify\-exact\fR \fImember\fR \fI[archive]\fR+
.PP
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-list\fR \fI[archive]\fR+
.PP
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-get\-hashes\fR \fIrole\fR \fI[archive|changes]\fR+
.PP
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-sign\-hashes\fR \fI[hashes\-archive]\fR+
.PP
\&\fBdpkg-sig\fR \fB[options]\fR \fB\-\-write\-signature\fR \fI[hashes\-archive]\fR+
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdpkg-sig\fR creates and verifies signatures on Debian archives (.deb\-files).
.PP
Use higher-level tools to install and remove packages from your system, 
and to verify a signature as acceptable for your system.
.PP
A usage example can be found at the end of this man page.
.SH "ACTION OPTIONS"
.IX Header "ACTION OPTIONS"
.IP "\fB\-\-sign\fR, \fB\-s\fR \fIrole\fR" 4
.IX Item "--sign, -s role"
Signs a standard-conforming Debian archive. \fIrole\fR gives the name of the
signature (usually 'builder' for the builder of the .deb).  The
signature is made using your default key, unless specified via any
explicit or implicit option (see below).
.Sp
If one or more .changes\-files are given, the md5sums inside the
\&.changes file(s) are also updated.
.Sp
If a .changes file was gpg-signed, the signature is removed when
updating the md5sums.
.IP "\fB\-\-verify\fR, \fB\-c\fR; \fB\-\-verify\-role\fR; \fB\-\-verify\-exact\fR" 4
.IX Item "--verify, -c; --verify-role; --verify-exact"
Verifies a signature on the given archive file. \fB\-\-verify\fR and \fB\-c\fR just
check all signatures; \fB\-\-verify\-role\fR verifies all signatures with a given
role, and \fB\-\-verify\-exact\fR wants the exact name of the archive member
(without the leading _gpg). However, both commands also accept perl regular
expressions as the name.
.Sp
All verify variants output (in turn for each signature) either a line 
consisting of \s-1GOODSIG,\s0 role, gpg-fingerprint and signature time (in
seconds since 1970\-1\-1 0:00:00 \s-1UTC\s0), or \s-1BADSIG.\s0
.Sp
Starting from version 0.12, \fBdpkg-sig\fR returns 2 if a bad signature
was found when trying to verify. If an unknown key was used to
sign a .deb, \fBdpkg-sig\fR returns 3.
.IP "\fB\-\-list\fR, \fB\-l\fR, \fB\-t\fR" 4
.IX Item "--list, -l, -t"
Lists all names inside the deb that look like a signature.
.IP "\fB\-\-get\-hashes\fR, \fB\-\-sign\-hashes\fR, \fB\-\-write\-signature\fR" 4
.IX Item "--get-hashes, --sign-hashes, --write-signature"
\&\fB\-\-get\-hashes\fR creates an \fBar\fR(1) archive containing a control file
part and files with the digests of all the .debs specified on the
command-line or named in the .changes file(s) specified on the
command-line.
.Sp
After that, you can transfer this (small) file to another machine, for 
example an offline system containing your gpg keys. (Yep, that's paranoid!)
.Sp
\&\fB\-\-sign\-hashes\fR then signs this file containing the digests (in fact,
it replaces the digests parts with their signatures).
.Sp
Now transfer the signed file back to the machine where you created the
hashes and use \fB\-\-write\-signature\fR to add the signatures from the archive
to the deb.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-m\fR \fImaintainer\fR" 4
.IX Item "-m maintainer"
Specify the maintainer name to be used for signing.
.IP "\fB\-e\fR \fImaintainer\fR" 4
.IX Item "-e maintainer"
Same as \fB\-m\fR but takes precedence.
.IP "\fB\-k\fR \fIkeyid\fR" 4
.IX Item "-k keyid"
Specify the key \s-1ID\s0 to be used for signing; overrides any \fB\-e\fR or \fB\-m\fR
option.
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
Get some more details.
.IP "\fB\-\-batch=1\fR" 4
.IX Item "--batch=1"
Gurantees that the non-verbose output will not change. Use this if you want
to parse the output.
.IP "\fB\-\-also\-v3\-sig\fR" 4
.IX Item "--also-v3-sig"
The signature format changed between version 0.10 and 0.11. If you want to
verify old signatures too, try this switch.
.IP "\fB\-\-also\-v2\-sig\fR" 4
.IX Item "--also-v2-sig"
The signature format changed between version 0.2 and 0.3. If you want to
verify old signatures too, try this switch.
.IP "\fB\-\-cache\-passphrase\fR, \fB\-p\fR" 4
.IX Item "--cache-passphrase, -p"
Caches the gpg-passphrase inside \fBdpkg-sig\fR. This needs the suggested
package \f(CW\*(C`libterm\-readkey\-perl\*(C'\fR.
.Sp
Be warned: Doing this is insecure, \fBdpkg-sig\fR doesn't protect the
memory it uses to store the passphrase.
.IP "\fB\-\-sign\-changes\fR, \fB\-a\fR [ no | auto | yes | full | force_full ]" 4
.IX Item "--sign-changes, -a [ no | auto | yes | full | force_full ]"
Tells whether also sign the .changes and .dsc\-files. The default is
\&\fIauto\fR, which means that the .changes\-file is re-signed if it was
signed before.
.Sp
The other values are \fIno\fR (don't sign .changes, and remove an existing
signature), \fIyes\fR (always add a signature to .changes), \fIfull\fR (always
add a signature to .changes, and also sign the .dsc\-file if there was
no previous signature; otherwise ask) and \fIforce_full\fR (always add a
signature to both the .changes and .dsc files).
.IP "\fB\-\-remote\-dpkg\-sig\fR, \fB\-r\fR \fIpath\fR" 4
.IX Item "--remote-dpkg-sig, -r path"
Use this if you want to specify where \fBdpkg-sig\fR can find the
\&\fBdpkg-sig\fR executable on the remote machine.
.Sp
This is useful if you're not able/allowed to install \fBdpkg-sig\fR as a .deb.
To do that, copy the script to something like \fI~/bin/dpkg\-sig\fR on the remote
system. After that, you can call your local \fBdpkg-sig\fR with something like the
following to use the remote signing/verifying features:
.Sp
\&\f(CW\*(C`dpkg\-sig \-\-sign builder \-r ~/bin/dpkg\-sig ssh://user@host:~/some\-deb_version_arch.changes\*(C'\fR
.IP "\fB\-\-remote\-ssh\-port\fR, \fB\-o\fR \fIport\fR" 4
.IX Item "--remote-ssh-port, -o port"
Port of the \fBsshd\fR on the remote host. Default value is 22.
.SH "MORE OPTIONS"
.IX Header "MORE OPTIONS"
These options should normally not be used, but are here for completeness.
Be warned: Use them only if you really know what you are doing.
.IP "\fB\-\-gpgoptions\fR, \fB\-g\fR \fIgpg options\fR" 4
.IX Item "--gpgoptions, -g gpg options"
Use this to pass arbitrary options to \fBgpg\fR(1) whenever a file is
signed. As this can lead to broken signatures, test your changes
carefully.
.IP "\fB\-\-passphrase\-file\fR, \fB\-f\fR \fIpassphrase file\fR" 4
.IX Item "--passphrase-file, -f passphrase file"
Tells gpg to use the passphrase in \fIfile\fR to sign.
.Sp
Be warned: Doing this is insecure, \s-1DON\s0'T use this feature.
However, in some cases (e.g. automatic signing on a buildd) this could be
useful, and is still better than using a gpg-key without passphrase. You
can gain at least some security by putting this file on a ramdisk, but it
would be better to use \fBgpg-agent\fR(1).
.SH "CONFIGURATION VARIABLES"
.IX Header "CONFIGURATION VARIABLES"
The two configuration files \fI/etc/devscripts.conf\fR and
\&\fI~/.devscripts\fR are sourced in that order to set configuration
variables.  Command line options can be used to override configuration
file settings.  Environment variable settings are ignored for this
purpose.  The currently recognised variables are:
.IP "\fB\s-1DEBSIGN_MAINT\s0\fR" 4
.IX Item "DEBSIGN_MAINT"
This is the \fB\-m\fR option.
.IP "\fB\s-1DEBSIGN_KEYID\s0\fR, \fB\s-1DPKGSIG_KEYID\s0\fR" 4
.IX Item "DEBSIGN_KEYID, DPKGSIG_KEYID"
This is the \fB\-k\fR option, and \fB\s-1DPKGSIG_KEYID\s0\fR has most precedence.
.IP "\fB\s-1DPKGSIG_SIGN_CHANGES\s0\fR" 4
.IX Item "DPKGSIG_SIGN_CHANGES"
This is the \fB\-\-sign\-changes\fR option. Valid values are \fIno\fR, \fIauto\fR,
\&\fIyes\fR, \fIfull\fR and \fIforce_full\fR.
.IP "\fB\s-1DPKGSIG_CACHE_PASS\s0\fR" 4
.IX Item "DPKGSIG_CACHE_PASS"
This is the \fB\-\-cache\-passphrase\fR option. Set this to a true value
to enable it.
.SH "SIGNATURE FORMAT"
.IX Header "SIGNATURE FORMAT"
The signatures created by \fBdpkg-sig\fR are added in a strict
standard-conforming way to the .deb archive file. The signature itself
is made on a file formatted like a Debian control file. The fields of
this file are: Version, specifying a \fBdpkg-sig\fR file version number;
Signer, giving the name of the signer; Date and Role, and finally
Files, which gives the digests of the prior contents of the .deb
archive file.  Note that this includes any prior signatures made by
\&\fBdpkg-sig\fR. Thus it is possible to verify any signature by hand with
just \fBar\fR(1), \fBmd5sum\fR(1), \fBsha1sum\fR(1) and \fBgpg\fR(1).  Signing a 
list of digests has the advantage that it is possible to perform remote
signatures without transferring the whole archive file.  This does
require one to trust the remote machine, though!
.SH "REMOTE SIGNING"
.IX Header "REMOTE SIGNING"
\&\fBdpkg-sig\fR can sign remote files using \fBssh\fR(1) without transferring
the whole file to the local machine, or the key to the remote
machine. Simply specify the file with
\&\f(CW\*(C`ssh://[user@]machine:/path/to/file\*(C'\fR, and have \fBdpkg-sig\fR installed
on the remote machine.  (See also the \fB\-\-remote\-dpkg\-sig\fR option
above.)
.PP
Remote signing supports the usual filename globbing.
.PP
Remote signing has been tested, but is at the moment considered a more
experimental feature.
.SH "BUGS, TODO"
.IX Header "BUGS, TODO"
\&\fBdpkg-sig\fR should be able to also verify signatures made by older
code.  This may be added in a later version.
.PP
\&\fBdpkg-sig\fR assumes that any given archive is strictly standard-compatible.
This is valid for archives created by \fBdpkg-deb\fR \- but if you're not sure 
about a archive, verify this yourself, or live with the risk of a bad 
signature.
.PP
More documentation about the signature format should be added.
.PP
Deal better with expired etc. keys and signatures.
.PP
Better inclusion into the other tools like \fBdpkg-buildpackage\fR.
.PP
And of course: Still missing is testing, testing and testing \fBdpkg-sig\fR.
.SH "USAGE EXAMPLE"
.IX Header "USAGE EXAMPLE"
A typical use is to sign packages before a (maintainer\-)upload. This can
be done by running \fBdpkg-buildpackage\fR and afterwards calling 
\&\f(CW\*(C`dpkg\-sig \-\-sign builder *.changes\*(C'\fR.
.PP
If you want to do all signing with \fBdpkg-sig\fR you could run 
\&\f(CW\*(C`dpkg\-buildpackage \-uc \-us\*(C'\fR and afterwards call 
\&\f(CW\*(C`dpkg\-sig \-\-sign builder \-\-sign\-changes full *.changes\*(C'\fR.
If you do this, there is no need to call \fBdebsign\fR any more, as
\&\fBdpkg-sig\fR does all the signing for you.
.PP
If you don't want to type in your passphrase multiple times, then you could
add the option \fB\-\-cache\-passphrase\fR.
.PP
The options \fB\-\-sign\-changes\fR and \fB\-\-cache\-passphrase\fR could be
replaced with setting the variables \fB\s-1DPKGSIG_SIGN_CHANGES\s0\fR respectivly
\&\fB\s-1DPKGSIG_CACHE_PASS\s0\fR (set the later one set to a true value) in 
\&\fI~/.devscripts\fR.
.PP
The key-id is automatically set from \fI/etc/devscripts.conf\fR and
\&\fI~/.devscripts\fR, but could be overridden via the \fB\-m\fR, \fB\-e\fR or \fB\-k\fR
command line options (see above).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdeb\fR(5), \fBdebsign\fR(1), \fBdpkg-deb\fR(8), \fI/usr/share/doc/dpkg\-sig/\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\fBdpkg-sig\fR and this manpage were written by Andreas Barth and Marc
Brockschmidt. They are Copyright (C) 2003\-2006 by them and released
under the \s-1GNU\s0 General Public Licence version 2 or later; there is \s-1NO
WARRANTY. \s0 See \fI/usr/share/doc/dpkg\-sig/copyright\fR and
\&\fI/usr/share/common\-licenses/GPL\fR for details. Some parts of this
manpage are taken from debsign.