Provided by: dpkg-sig_0.13.1_all bug

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.