DPKG-SIG(7)						      Debian GNU/Linux manual						       DPKG-SIG(7)

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/com-
       mon-licenses/GPL for details.

Debian Project							    2006-11-20							       DPKG-SIG(7)