DPKG-SIG(1)

📦 version 0.13.1, in ubuntu jammy

👑 DPKG-SIG(1) — the Debian GNU/Linux manual page, but make it bestie-coded

okay so. gather round. this is dpkg-sig, from the Debian GNU/Linux manual, and it is genuinely one of my faves because it's the girl who signs your .deb files and then checks everybody else's signatures. she's giving cryptography but make it cute. let's go 💅

✨ NAME ✨

dpkg-sig — the Debian package archive (.deb) signature generation and verification tool. yes, that's her whole job. iconic.

🌸 SYNOPSIS 🌸

dpkg-sig [options] --sign role [archive|changes]+

dpkg-sig [options] --verify [archive]+

dpkg-sig [options] --verify-role role [archive]+

dpkg-sig [options] --verify-exact member [archive]+

dpkg-sig [options] --list [archive]+

dpkg-sig [options] --get-hashes role [archive|changes]+

dpkg-sig [options] --sign-hashes [hashes-archive]+

dpkg-sig [options] --write-signature [hashes-archive]+

like. pick a mode, pick your files, and she does the thing. no cap.

💖 DESCRIPTION 💖

dpkg-sig creates and verifies signatures on Debian archives (the .deb-files, you know the ones).

okay real talk though: use the higher-level tools to install and remove packages from your system, and to verify a signature as acceptable for your system. she's not out here replacing dpkg bestie, she's a specialist 🫶

there's a usage example waiting for you at the end of this man page. it's giving tutorial. obsessed.

🔥 ACTION OPTIONS 🔥

  • --sign, -s role — signs a standard-conforming Debian archive. role 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).

If one or more .changes-files are given, the md5sums inside the .changes file(s) are also updated.

If a .changes file was gpg-signed, the signature is removed when updating the md5sums. yes literally removed. heads up. 😭

  • --verify, -c; --verify-role; --verify-exact — verifies a signature on the given archive file. --verify and -c just check all signatures; --verify-role verifies all signatures with a given role, and --verify-exact wants the exact name of the archive member (without the leading _gpg). However, both commands also accept perl regular expressions as the name. so you can be a lil loose with it, she'll figure it out ✨

All verify variants output (in turn for each signature) either a line consisting of GOODSIG, role, gpg-fingerprint and signature time (in seconds since 1970-1-1 0:00:00 UTC), or BADSIG. the two moods. GOODSIG is the slay, BADSIG is the 💀

Starting from version 0.12, dpkg-sig returns 2 if a bad signature was found when trying to verify. If an unknown key was used to sign a .deb, dpkg-sig returns 3.

  • --list, -l, -t — lists all names inside the deb that look like a signature. little signature census. so real.
  • --get-hashes, --sign-hashes, --write-signature — --get-hashes creates an ar(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.

After that, you can transfer this (small) file to another machine, for example an offline system containing your gpg keys. (Yep, that's paranoid!) — her words not mine, but honestly? valid. 🔒

--sign-hashes then signs this file containing the digests (in fact, it replaces the digests parts with their signatures).

Now transfer the signed file back to the machine where you created the hashes and use --write-signature to add the signatures from the archive to the deb. round trip bestie. she travels 🦋

💜 OPTIONS 💜

  • -m maintainer — specify the maintainer name to be used for signing.
  • -e maintainer — same as -m but takes precedence. she wins the argument, always 👑
  • -k keyid — specify the key ID to be used for signing; overrides any -e or -m option. top of the food chain.
  • --verbose — get some more details. she'll yap. affectionately.
  • --batch=1 — gurantees that the non-verbose output will not change. Use this if you want to parse the output. (yes the typo is hers, we respect the typo, it's canon 💅) basically: this is the "please be predictable" switch.
  • --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.
  • --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.
  • --cache-passphrase, -p — caches the gpg-passphrase inside dpkg-sig. This needs the suggested package "libterm-readkey-perl".
Be warned: Doing this is insecure, dpkg-sig doesn't protect the memory it uses to store the passphrase. like. the passphrase is just sitting there. in memory. unguarded. 🙈
  • --sign-changes, -a [ no | auto | yes | full | force_full ] — tells whether also sign the .changes and .dsc-files. The default is auto, which means that the .changes-file is re-signed if it was signed before.

The other values are no (don't sign .changes, and remove an existing signature), yes (always add a signature to .changes), full (always add a signature to .changes, and also sign the .dsc-file if there was no previous signature; otherwise ask) and force_full (always add a signature to both the .changes and .dsc files). pick your fighter 🎀

  • --remote-dpkg-sig, -r path — use this if you want to specify where dpkg-sig can find the dpkg-sig executable on the remote machine.

This is useful if you're not able/allowed to install dpkg-sig as a .deb. To do that, copy the script to something like ~/bin/dpkg-sig on the remote system. After that, you can call your local dpkg-sig with something like the following to use the remote signing/verifying features:

"dpkg-sig --sign builder -r ~/bin/dpkg-sig
ssh://user@host:~/some-deb_version_arch.changes"
  • --remote-ssh-port, -o port — port of the sshd on the remote host. Default value is 22. the classic. the default. the moment.

🌈 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. she's not gatekeeping, she's just worried about you 🥺

  • --gpgoptions, -g gpg options — use this to pass arbitrary options to gpg(1) whenever a file is signed. As this can lead to broken signatures, test your changes carefully. like, actually test them. fr fr.
  • --passphrase-file, -f passphrase file — tells gpg to use the passphrase in file to sign.
Be warned: Doing this is insecure, DON'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 gpg-agent(1). bestie please use gpg-agent(1). she's begging. 😭

🧚 CONFIGURATION VARIABLES 🧚

The two configuration files /etc/devscripts.conf and ~/.devscripts 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:

  • DEBSIGN_MAINT — this is the -m option.
  • DEBSIGN_KEYID, DPKGSIG_KEYID — this is the -k option, and DPKGSIG_KEYID has most precedence. she's the final boss of key ids 👑
  • DPKGSIG_SIGN_CHANGES — this is the --sign-changes option. Valid values are no, auto, yes, full and force_full.
  • DPKGSIG_CACHE_PASS — this is the --cache-passphrase option. Set this to a true value to enable it.

⭐ SIGNATURE FORMAT ⭐

The signatures created by dpkg-sig 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 dpkg-sig 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 dpkg-sig. Thus it is possible to verify any signature by hand with just ar(1), md5sum(1), sha1sum(1) and gpg(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!

so basically: it's a control-file-shaped receipt, and you can hand-verify the whole thing with four tools if you're feeling feral. iykyk 💅

🦋 REMOTE SIGNING 🦋

dpkg-sig can sign remote files using ssh(1) without transferring the whole file to the local machine, or the key to the remote machine. Simply specify the file with "ssh://[user@]machine:/path/to/file", and have dpkg-sig installed on the remote machine. (See also the --remote-dpkg-sig option above.)

Remote signing supports the usual filename globbing. ✨

Remote signing has been tested, but is at the moment considered a more experimental feature. so like. she's confident but she's not cocky. ⚠️

💀 BUGS, TODO 💀

  • dpkg-sig should be able to also verify signatures made by older code. This may be added in a later version.
  • dpkg-sig assumes that any given archive is strictly standard-compatible. This is valid for archives created by dpkg-deb — but if you're not sure about a archive, verify this yourself, or live with the risk of a bad signature. (yes, "a archive". canon. we love her.)
  • More documentation about the signature format should be added.
  • Deal better with expired etc. keys and signatures.
  • Better inclusion into the other tools like dpkg-buildpackage.
  • And of course: Still missing is testing, testing and testing dpkg-sig. she said it three times so you KNOW she means it 🫶

🎀 USAGE EXAMPLE 🎀

A typical use is to sign packages before a (maintainer-)upload. This can be done by running dpkg-buildpackage and afterwards calling "dpkg-sig --sign builder *.changes".

If you want to do all signing with dpkg-sig you could run "dpkg-buildpackage -uc -us" and afterwards call "dpkg-sig --sign builder --sign-changes full *.changes". If you do this, there is no need to call debsign any more, as dpkg-sig does all the signing for you. she's doing it all. main character energy, honestly. 👑

If you don't want to type in your passphrase multiple times, then you could add the option --cache-passphrase.

The options --sign-changes and --cache-passphrase could be replaced with setting the variables DPKGSIG_SIGN_CHANGES respectivly DPKGSIG_CACHE_PASS (set the later one set to a true value) in ~/.devscripts. (again: her typos, her voice, we preserve them 💖)

The key-id is automatically set from /etc/devscripts.conf and ~/.devscripts, but could be overridden via the -m, -e or -k command line options (see above).

💜 SEE ALSO 💜

deb(5), debsign(1), dpkg-deb(8), /usr/share/doc/dpkg-sig/

🌸 AUTHOR 🌸

dpkg-sig and this manpage were written by Andreas Barth and Marc Brockschmidt. They are Copyright (C) 2003-2006 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. Some parts of this manpage are taken from debsign.

and that's the whole page, bestie!! written by the Debian Project, dated 2016-12-19, and she lives at DPKG-SIG(1) — go sign something and slay 💅✨🎀

📦 where this page comes from