debsig-verify(1)

✨ debsig-verify ✨

okay bestie, sit down, hydrate, and let me tell you about debsig-verify 💖 — it's the dpkg suite's little bouncer that checks IDs at the door of your Debian packages. no cap.

---

🌸 NAME 🌸

debsig-verify — verify signatures for a Debian format package 🫶

---

🎀 SYNOPSIS 🎀

debsig-verify [option...] deb

---

💅 DESCRIPTION 💅

so this program is part of a whole security model that verifies the source and validity of a Debian format package — you know her, you love her, she's commonly called a deb 🦋

it implements the verification specs laid out in the document "Package Verification with dpkg: Implementation", which is the more complete reference for the whole verification procedure, iykyk.

generally it takes one argument — the deb file that needs verifying. then it:

1. checks the origin signature of the deb
2. finds its Public Key ID (long format, bestie, LONG)
3. uses that ID as the name for a policy subdirectory

and if that subdirectory doesn't exist? 💀 verification fails immediately. like, instantly. no second chances. periodt.

in that subdirectory, the program finds one or more files named with the .pol file extension — that's an XML format policy definition. this file has three main parts:

• Origin — Information about the origin of this policy.
• Selection — Rules used to decide if this policy is pertinent to this deb's verification.
• Verification — Rules that are used to actually verify the deb.

the policy files reference OpenPGP keyrings by a filename, and those keyrings get looked up inside a subdirectory of the OpenPGP keyring directory. that subdirectory has the same name as the policy subdirectory (which, remember, was already determined by the Origin's Public Key ID ✨).

after it parses the entire file, the program checks the Origin ID against the Public Key ID of the origin signature in the deb. if those match — which they should, otherwise something is really wrong 😭 — it moves on to the Selection rules.

the Selection rules decide whether this policy is even suitable for verifying this deb. if they fail, the program just goes to the next policy, no drama. but if they pass? it commits to that policy for verification, and no other policies get referenced. main character policy energy, honestly 👑

the last verification step rides on the Verification rules. they're similar in format to the Selection rules but usually way more constrained. if they fail → program exits with a non-zero status. if they pass → exits with a zero status. slay 💅

---

🌈 OPTIONS 🌈

• -q, --quiet — makes the program send no output at all, other than fatal errors. super useful when another program is calling it and you're only relying on the exit value, fr fr.
• -v, --verbose — makes the program send more output while it runs, so you can follow along with every step it takes trying to verify the deb. it's giving commentary track 🎀
• -d, --debug — outputs even MORE info than -v. mainly for debugging, bestie.
• --help — outputs the usage information for the program.
• --version — outputs the version information for the program. this includes the policy format version. this option does not require any other arguments ✨
• --list-policies — outputs a list of the policies that passed the Selection phase of the verification process. in other words, the ones that could potentially verify the deb. the output is one line showing the directory selected by the origin signature, and then a single line for any policy files in that directory that pass the Selection rules. > heads up: this option will NOT verify the deb. it's just window shopping 🛍️
• --use-policy policy — takes one argument: the name of the policy file (as shown by the --list-policies option). note that this is just a file, not a full path — you cannot specify arbitrary policies. this option is useful if more than one policy applies to potentially verifying the deb. the program will then use this policy, and only this policy, to try and verify the deb.
• --policies-dir directory — use a different directory when looking up for policies.
• --keyrings-dir directory — use a different directory when looking up for OpenPGP keyrings.
• --root directory — use a different root directory when looking up for policies and OpenPGP keyrings.

---

🔥 EXIT STATUS 🔥

• 0 — the requested operation completed successfully. 🎉 iconic.
• 1 — general non-success exit value. this happens for non-verification operations.
• 10 — either no signatures are contained in the deb, or no origin signature was found. 💀
• 11 — an origin signature was found, but it doesn't have a corresponding subdirectory in the policies directory. 🙈
• 12 — the origin was found, and it is present. however, no policies were found that passed the selection phase of the process. thus, no verification was performed.
• 13 — the package failed the verification phase of the process. more than likely this happens because of a bad signature, or because not all criteria of the verification block of the policy were passed. 😭
• 14 — an internal error occurred. this is an unrecoverable error. either the deb is corrupt, the OpenPGP backend failed abnormally, or some other uncontrollable failure. genuinely the worst timeline.

---

🦋 ENVIRONMENT 🦋

• DEBSIG_GNUPG_PROGRAM — the name (or pathname) of the GnuPG program to use.

---

🧚 FILES 🧚

• /etc/debsig/policies/ — directory containing the policy (.pol) definitions.
• /etc/debsig/policies/*/*.pol — XML format policy files.
• /usr/share/debsig/keyrings/ — directory containing the OpenPGP keyrings (*.pgp) that coincide with the policies.
• /usr/share/debsig/keyrings/*/*.pgp
• /usr/share/debsig/keyrings/*/*.gpg — OpenPGP format keyrings for use by the policies.

note: the .gpg extensions are the legacy names, used because of the prevalence of one of the OpenPGP implementations. these keyrings must be in OpenPGP keyring format, and not some tool specific format (such as GnuPG keybox databases). no shortcuts, bestie 🙅‍♀️

---

⭐ SEE ALSO ⭐

debsigs(1), gpg(1), deb(5).

---

and that's the whole vibe check 💜 this was debsig-verify(1) from the dpkg suite, version 0.34 — go forth and verify those debs, you gorgeous genius, you 🫶✨🌸