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