.\" 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 7"
.TH DPKG-SIG 7 "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 "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the description of the source code, trying to help people to understand
how \fBdpkg-sig\fR works.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "\fI\e@file_info\fP = sign_deb (\fI\fP\f(CI$signing_role\fP\fI\fP, \fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "@file_info = sign_deb ($signing_role, $file)"
Does everything needed to add a signature to \fI\f(CI$file\fI\fR:
.IP "\(bu" 4
Verifies existing signatures
.IP "\(bu" 4
Creates the meta-data that is actually signed
.IP "\(bu" 4
Calls gpg to sign the meta-data.
.IP "\(bu" 4
Adds the signature to \fI\f(CI$file\fI\fR
.PP
Returns a reference to an array containing the new md5sum, the new size
and the name of the signed deb.
.SS "\fI\fP\f(CI$signature_name\fP\fI\fP = write_deb_info (\fI\fP\f(CI$signing_role\fP\fI\fP, \fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "$signature_name = write_deb_info ($signing_role, $file)"
Creates a digests.asc file with the meta-data of \fI\f(CI$file\fI\fR in dpkg-sig's tempdir:
.IP "\(bu" 4
Gets the needed information from \fI\f(CI$file\fI\fR
.IP "\(bu" 4
Chooses the name of the signature
.IP "\(bu" 4
Writes a file in a RFC822\-like format containing the meta-data
.PP
Returns the name that should be used to add the file to the deb.
.SS "sign_hashes (\fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "sign_hashes ($file)"
Signs a .dpkg\-sig\-hashes \fI\f(CI$file\fI\fR containing the digests of a deb/changes file:
.IP "\(bu" 4
Checks the .dpkg\-sig\-hashes file to see if it really was created by us
.IP "\(bu" 4
Creates a new archive, containing the old control file
.IP "\(bu" 4
Signs the digests and adds the clearsigned data to the the new archive
.IP "\(bu" 4
Substitutes the old file by the new, signed one.
.SS "\fI\fP\f(CI@changed_files\fP\fI\fP = write_signature (\fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "@changed_files = write_signature ($file)"
Adds the signatures from a signed .dpkg\-sig\-hashes \fI\f(CI$file\fI\fR to the signed debs:
.IP "\(bu" 4
Checks the .dpkg\-sig\-hashes file to see if it really was created by us
.IP "\(bu" 4
Tries to find out where we find the debs that have sigs in the .dpkg\-sig\-hashes
.IP "\(bu" 4
Checks if the debs were changed since they were signed
.IP "\(bu" 4
Adds signatures from the .dpkg\-sig\-hashes file to the debs
.IP "\(bu" 4
If needed, it corrects the changes file to reflect the new sizes/md5sums of the debs
.PP
Returns the pathes of the debs that were changed.
.SS "\fI\fP\f(CI@output\fP\fI\fP = verify_deb (\fI\fP\f(CI$deb\fP\fI\fP, \fI\fP\f(CI$verify_pattern\fP\fI\fP)"
.IX Subsection "@output = verify_deb ($deb, $verify_pattern)"
Verifies all signatures in \fI\f(CI$deb\fI\fR with names matching \fI\f(CI$verify_pattern\fI\fR:
.IP "\(bu" 4
Gets the digests of all parts of \fI\f(CI$deb\fI\fR.
.IP "\(bu" 4
Skips all signatures that don't match \fI\f(CI$verify_pattern\fI\fR.
.IP "\(bu" 4
Writes the signatures to \f(CW$tempdir\fR/digests.asc.
.IP "\(bu" 4
Calls a function to check if \f(CW$tempdir\fR/digests.asc is valid in the v4 format, then tries v3 and v2.
.PP
Returns its output. This is needed to achieve a \*(L"silent\*(R" verification when signing a deb.
.SS "\fI\fP\f(CI$verification_status\fP\fI\fP = verify_deb_sig_v4 (\fI\fP\f(CI$part_name\fP\fI\fP, \fI\fP\f(CI$part_number\fP\fI\fP, \fI\e@digests\fP, \fI\e@info\fP, \fI\e@return\fP)"
.IX Subsection "$verification_status = verify_deb_sig_v4 ($part_name, $part_number, @digests, @info, @return)"
Verifies if \f(CW$tempdir\fR/digests is a valid (version 4) signature for the deb described with \fI\e@digests\fR:
.IP "\(bu" 4
Calls gpg to verify the OpenPGP signature in \f(CW$tempdir\fR/digests.asc itself.
.IP "\(bu" 4
Parses the signature to get the digests that were actually signed
.IP "\(bu" 4
Compare the digests of the deb and those extracted from the signature to see if the deb was changed.
.IP "\(bu" 4
Check that the name in the ar archive matches the \*(L"Role\*(R" field in the signature.
.IP "\(bu" 4
\&\s-1DON\s0'T check the Signer\- and Date-Fiels.
.IP "\(bu" 4
Check that at least the digests for control.tar.gz, data.tar.gz and debian-binary were signed.
.PP
Returns if the the signature is good, by an unknown key, or bad.
.SS "\fI\fP\f(CI$verification_status\fP\fI\fP = verify_deb_sig_v3 (\fI\fP\f(CI$part_name\fP\fI\fP, \fI\fP\f(CI$part_number\fP\fI\fP, \fI\e@digests\fP, \fI\e@info\fP, \fI\e@return\fP)"
.IX Subsection "$verification_status = verify_deb_sig_v3 ($part_name, $part_number, @digests, @info, @return)"
Verifies if \f(CW$tempdir\fR/digests is a valid (version 3) signature for the deb described with \fI\e@digests\fR:
.IP "\(bu" 4
Creates a file in \f(CW$tempdir\fR/digests that contains the signing role and the digests from the current deb.
.IP "\(bu" 4
Calls gpg to verify that the detached OpenPGP signature in \f(CW$tempdir\fR/digests.asc is valid for \f(CW$tempdir\fR/digests.
.PP
Returns if the the signature is good, by an unknown key, or bad.
.SS "\fI\fP\f(CI$verification_status\fP\fI\fP = verify_deb_sig_v2 (\fI\fP\f(CI$part_name\fP\fI\fP, \fI\fP\f(CI$part_number\fP\fI\fP, \fI\e@digests\fP, \fI\e@info\fP, \fI\e@return\fP)"
.IX Subsection "$verification_status = verify_deb_sig_v2 ($part_name, $part_number, @digests, @info, @return)"
Verifies if \f(CW$tempdir\fR/digests is a valid (version 2) signature for the deb described with \fI\e@digests\fR:
.IP "\(bu" 4
Creates a file in \f(CW$tempdir\fR/digests that contains the digests from the current deb.
.IP "\(bu" 4
Calls gpg to verify that the detached OpenPGP signature in \f(CW$tempdir\fR/digests.asc is valid for \f(CW$tempdir\fR/digests.
.PP
Returns if the the signature is good, by an unknown key, or bad.
.SS "\fI\fP\f(CI$sig_name\fP\fI\fP = get_sig_name (\fI\fP\f(CI$sig_name\fP\fI\fP, \fI\e@parts\fP, \fI\fP\f(CI$deb\fP\fI\fP)"
.IX Subsection "$sig_name = get_sig_name ($sig_name, @parts, $deb)"
Tries to find a filename for the signature. Receives the role and constructs
a name not already present in \fI\f(CI$deb\fI\fR.
.PP
Returns the final name or dies if it wasn't possible to construct a name.
.SS "correct_changes_file (\fI\fP\f(CI$changes\fP\fI\fP, \fI\e%new_deb_info\fP)"
.IX Subsection "correct_changes_file ($changes, %new_deb_info)"
Receives a path to a changes file \fI\f(CI$changes\fI\fR and a hash reference 
\&\fI\e%new_deb_info\fR containing new sizes and md5sums of debs in that changes
file. It'll parse the changes file, replace the old values by the new ones.
If the file is signed, the signature will be stripped (as it would be 
invalid anyway).
.SS "\fI\e@new_file_info\fP = add_part_to_ar_archive (\fI\fP\f(CI$file\fP\fI\fP, \fI\fP\f(CI$new_data\fP\fI\fP, \fI\fP\f(CI$new_name\fP\fI\fP)"
.IX Subsection "@new_file_info = add_part_to_ar_archive ($file, $new_data, $new_name)"
.SS "\fI\e@new_file_info\fP = add_sig_to_deb (\fI\fP\f(CI$file\fP\fI\fP, \fI\fP\f(CI$new_data\fP\fI\fP, \fI\fP\f(CI$new_name\fP\fI\fP)"
.IX Subsection "@new_file_info = add_sig_to_deb ($file, $new_data, $new_name)"
Adds \fI\f(CI$new_data\fI\fR to \fI\f(CI$file\fI\fR as new ar archiv part, using \f(CW$new_name\fR as 
filename. If \fI\f(CI$file\fI\fR doesn't exist, a new ar archive is created. Returns
the new md5sum and size of \fI\f(CI$file\fI\fR.
.SS "\fI\fP\f(CI@parts\fP\fI\fP = get_ar_parts (\fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "@parts = get_ar_parts ($file)"
.SS "\fI\fP\f(CI@parts\fP\fI\fP = get_deb_parts (\fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "@parts = get_deb_parts ($file)"
Parses \fI\f(CI$file\fI\fR as ar archive and returns all filenames included in the archive.
.SS "\fI\fP\f(CI@debs\fP\fI\fP = get_debs_from_changes (\fI\fP\f(CI$file\fP\fI\fP, \fI\e$changes_signed\fP)"
.IX Subsection "@debs = get_debs_from_changes ($file, $changes_signed)"
Parses \fI\f(CI$file\fI\fR as Debian .changes file and returns all listed debs. The dirname
of \fI\f(CI$file\fI\fR is prepended to the debs, which means that the returned URIs should
exist.
If \fI\f(CI$file\fI\fR is signed, \fI\f(CI$changes_signed\fI\fR is set to \*(L"yes\*(R".
.SS "\fI\e@digests\fP = get_deb_digests (\fI\fP\f(CI$deb\fP\fI\fP)"
.IX Subsection "@digests = get_deb_digests ($deb)"
Parses \fI\f(CI$deb\fI\fR and returns the meta-data of the included files. The read
data is piped to md5sums and sha1sums, which create the respective 
digests. The digests, the filename and the size are put in an anymous
array looking like this: [\fB\f(CB$name\fB\fR, \fB\f(CB$size\fB\fR, \fB\f(CB$sha1sum\fB\fR, \fB\f(CB$md5sum\fB\fR].
One of these arrays is pushed to \fI\f(CI@digests\fI\fR for every file in \fI\f(CI$deb\fI\fR.
.SS "\fI\fP\f(CI$md5sum\fP\fI\fP = get_file_md5sum (\fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "$md5sum = get_file_md5sum ($file)"
Returns the md5sum for \fI\f(CI$file\fI\fR.
.SS "\fI\fP\f(CI$part_data\fP\fI\fP = get_archive_part (\fI\fP\f(CI$archive\fP\fI\fP, \fI\fP\f(CI$part_name\fP\fI\fP)"
.IX Subsection "$part_data = get_archive_part ($archive, $part_name)"
Returns the content of \fI\f(CI$part_name\fI\fR in the ar archive \fI\f(CI$archive\fI\fR.
.SS "\fI\fP\f(CI@file_data\fP\fI\fP = read_control_file (\fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "@file_data = read_control_file ($file)"
Returns the content of \fI\f(CI$file\fI\fR as array with one line per element.
.SS "\fI\fP\f(CI@file_info\fP\fI\fP = write_control_file (\fI\fP\f(CI$file\fP\fI\fP, \fI\e@data\fP)"
.IX Subsection "@file_info = write_control_file ($file, @data)"
Writes contents of \fI\e@data\fR to \fI\f(CI$file\fI\fR. Returns new md5sum and size
of \fI\f(CI$file\fI\fR.
.SS "\fI\fP\f(CI@files\fP\fI\fP = glob_exp (\fI\fP\f(CI$exp\fP\fI\fP)"
.IX Subsection "@files = glob_exp ($exp)"
Returns the result of globbing \fI\f(CI$exp\fI\fR as array.
.SS "\fI\fP\f(CI$file_readable\fP\fI\fP = file_readable (\fI\fP\f(CI$file\fP\fI\fP)"
.IX Subsection "$file_readable = file_readable ($file)"
Returns a true value if \fI\f(CI$file\fI\fR is readable.
.SS "\fI\fP\f(CI@ssh_uri_parts\fP\fI\fP = split_ssh_uri (\fI\fP\f(CI$uri\fP\fI\fP)"
.IX Subsection "@ssh_uri_parts = split_ssh_uri ($uri)"
Splits an ssh \s-1URI\s0 \f(CW$uri\fR into a \fB\f(CB$user\fB\fR, \fB\f(CB$host\fB\fR and \fB\f(CB$path\fB\fR part.
.SS "\fI\fP\f(CI@ssh_connection_info\fP\fI\fP = get_ssh_connection (\fI\fP\f(CI$user\fP\fI\fP, \fI\fP\f(CI$host\fP\fI\fP)"
.IX Subsection "@ssh_connection_info = get_ssh_connection ($user, $host)"
Opens a ssh connection to \fI\f(CI$host\fI\fR as user \fI\f(CI$user\fI\fR, directly calling 
\&\fBdpkg-sig\fR. It checks if the remote \fBdpkg-sig\fR is compatible to the
current version and returns the \fB\f(CB$pid\fB\fR, the Read-Filehandle \fB\f(CB$readerfh\fB\fR
and the Write-Filehandle \fB\f(CB$writerfh\fB\fR.
.SS "sign_control_files (\fI\fP\f(CI$changes_file\fP\fI\fP)"
.IX Subsection "sign_control_files ($changes_file)"
This works like debsign:
.IP "Checks if a .dsc exists." 4
.IX Item "Checks if a .dsc exists."
.PD 0
.IP "If the .dsc should be signed, it tries to do so.." 4
.IX Item "If the .dsc should be signed, it tries to do so.."
.IP "Writes the new .dsc with the new signature." 4
.IX Item "Writes the new .dsc with the new signature."
.IP "Reads \fI\f(CI$changes_file\fI\fR and puts in the new size/md5sum of the .dsc." 4
.IX Item "Reads $changes_file and puts in the new size/md5sum of the .dsc."
.IP "Signs \fI\f(CI$changes_file\fI\fR and write the signed copy back." 4
.IX Item "Signs $changes_file and write the signed copy back."
.PD
.SS "sign_file (\fI\fP\f(CI$in_file\fP\fI\fP, \fI\fP\f(CI$out_file\fP\fI\fP, \fI\fP\f(CI$no_detach\fP\fI\fP)"
.IX Subsection "sign_file ($in_file, $out_file, $no_detach)"
Signs \fI\f(CI$in_file\fI\fR with gpg and puts the detached signature in \fI\f(CI$out_file\fI\fR.
.PP
If \fI\f(CI$no_detach\fI\fR is true, \fI\f(CI$out_file\fI\fR is a clearsigned copy of \fI\f(CI$in_file\fI\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\fBdpkg-sig\fR and this manpage were written by Andreas Barth und Marc 
Brockschmidt. They are Copyright (C) 2003, 2004 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.