SOPV(1)

📦
version 1.1.1 · 2 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

SOPV(1) — Stateless OpenPGP Signature Verification

okay bestie, welcome to sopv 💖 this is the verification-only slice of the whole thing, and yes the manual name is right there in the title, we're not being weird about it.

✨ NAME ✨

sopv — verify OpenPGP signatures 🫶

✨ SYNOPSIS ✨

sopv [--debug] subcommand

✨ DESCRIPTION ✨

so like, sopv is the verification-only subset of the OpenPGP Stateless Command Line Interface — you might know it as "SOP" 💅

sopv was literally built to verify OpenPGP signatures. That's the whole vibe. It handles detached signatures and inline signatures, no problem. And how does it know who's allowed to have signed? You, the caller, hand it a set of OpenPGP certificates. That's the guest list. If you're not on it, you're not getting in 🚫✨

✨ EXAMPLES ✨

first up, the lil "who even are you" check:

$ sopv version
ExampleSop 2.3.0

then a detached signature verification, classic:

$ sopv verify libfoo-3.1.2.tgz.sig libfoo-keys.pgp < libfoo-3.1.2.tgz
2025-02-03T0:02:25Z 8CD219FC05D9DE9F3D59B784160B8EF5536B0D27 8CD219FC05D9DE9F3D59B784160B8EF5536B0D27 mode:binary {"signers":["libfoo-keys.pgp"]}

and an inline verify, with the receipts saved to a file 😌

$ sopv inline-verify --verifications-out=verifs.txt alice.cert < alice-message.csf
This is a message from Alice
$ cat verifs.txt
2025-02-13T00:04:49Z 63339423454CA210DAA886C08723C4D38E0802F6 F255F2A602AC1DFF2331085E5DAE32C783FC418D mode:text {"signers":["alice.cert"]}
$

want to do a thing only when a detached signature is valid? say less:

if sopv verify libfoo-3.1.2.tgz.sig libfoo-keys.pgp < libfoo-3.1.2.tgz > /dev/null; then
  # The software was signed correctly ...
fi

and same energy, but inline this time:

if sopv inline-verify alice.cert < alice-message.csf > alice.message; then
  # alice.message is data that was signed by alice ...
fi

✨ SUBCOMMANDS ✨

Exactly one subcommand must be supplied. one. not zero. not two. exactly one, bestie 🙈
  • sopv version — get all the version / build / compatibility info about the sopv implementation you're running. more deets in sopv-version(1) ✨
  • sopv verify — verify detached OpenPGP signatures over a message. more deets in sopv-verify(1) 💖
  • sopv inline-verify — verify an inline-signed OpenPGP message. more deets in sopv-inline-verify(1) 🦋

✨ COMMON OPTIONS ✨

every single sopv subcommand accepts this one, no exceptions:

  • --debug — emits more detailed output on standard error, if available. key phrase: if available. don't come for me if it's quiet 💀

each subcommand also has its own distinct options and arguments — go read the matching manual page, iykyk 👑

✨ INPUT DATA TYPES ✨

some sopv subcommands take these data types as inputs — either as arguments or straight off standard input. let's get into it:

  • DATE — dates are given directly in ISO-8601-compliant format, in UTC with the Z suffix. like, for example, 2025-02-12T05:22:33Z ⭐
  • CERTS — a collection of OpenPGP certificates, also known as "Transferable Public Keys". each CERTS input may be unarmored, or may use OpenPGP ASCII armor 🎀
  • SIGNATURES — a collection of OpenPGP signatures. each individual SIGNATURES input may be unarmored, or may use OpenPGP ASCII armor 💜
  • INLINESIGNED — an OpenPGP Signed Message, or a text document that is signed internally with the OpenPGP Cleartext Signing Framework. an OpenPGP Signed Message input may be unarmored, or may use OpenPGP ASCII armor 🌸

✨ VERIFICATIONS ✨

sometimes sopv emits a VERIFICATIONS text stream, and it's lowkey iconic — it holds a concise description of every valid OpenPGP signature it discovered 👑

every line in a VERIFICATIONS stream = one valid signature from an acceptable signer. there are at least three fixed fields, separated from each other — and from the final optional fields — by whitespace.

the fields, in order:

  • timestamp — the time of the signature, in ISO-8601 date format, in UTC ⏰
  • signing_key_fingerprint — the fingerprint of the signing key (may be a primary key, or a signing-capable subkey)
  • primary_key_fingerprint — the fingerprint of the primary key of the OpenPGP certificate that contains the signing key (may be the same as the signing key) 🔑
  • signing_mode — this optional field is either mode:text or mode:binary 💅
  • optional_additional_data — if signing_mode is present, the final optional field extends to the end of the line, and is either free-form text or a JSON object. if it starts with { it's a JSON object. that JSON object may contain a "signers" member, which is a JSON list of the names of each CERTS object that could have authored the signature 🫶

✨ SPECIAL DESIGNATORS ✨

anywhere a CERTS, SIGNATURES, or VERIFICATIONS object gets pointed to on the command line, it's typically given as a path to a filename. but also? sopv should accept a special designator, which is any string starting with a @ character 🌈

there are two established kinds of special designator:

  • @FD:nnn — this means read from, or write to, the file descriptor identified numerically by nnn. ngl this is also a valid argument for --verifications-out in sop inline-verify — you can use it there to run sopv on an entirely read-only filesystem 👑
  • @ENV:varname — this means read the value from the environment variable named varname. heads up: typically only text-based data can travel this way, so a CERTS argument should be armored, for example. also note this can only be used for input to sopv, never output — because sopv can't set the values in its callers' environment, bestie, it's not a wizard 🧚
if you want to refer to a file in the filesystem whose name actually begins with an @ (like, say, @foo), you should indicate that file to sopv using ./@foo to avoid an AMBIGUOUS_INPUT error ⚠️

✨ VERSION HISTORY ✨

the sopv specification keeps a version history similar to semantic versioning — https://semver.org/ 💖 implementations indicate their compliance with a specific level of the spec with sopv version --sopv (peep sopv-version(1)).

  • 1.1 — everything from 1.0. additionally, the VERIFICATIONS output includes the fourth field (signing_mode), and the final field of VERIFICATIONS is a JSON object containing at least a "signers" member as described above ✨
  • 1.0 — the subcommands version, verify, and inline-verify. the common argument --debug (even if it produces no additional messages to stderr). sopv version arguments --extended, --sop-spec, --backend, --sopv. for sopv verify and sopv inline-verify, the arguments --not-before and --not-after. for sopv inline-verify, the --verifications-out argument. special designators @ENV: and @FD: for any CERTS and SIGNATURES input. special designator @FD: for any VERIFICATIONS output. at least the first three fields in any VERIFICATIONS output 🎀

💖 RETURN CODES 💖

okay bestie, so sopv tells you it worked by returning 0. that's the good ending, that's the slay.

A failure? That's any non-zero return code, and honestly the codes are kinda specific so you can lowkey tell what went wrong. Here's the whole roster, no skips:

  • 0 — mnemonic OK — success. periodt. ✨
  • 1 — mnemonic UNSPECIFIED_FAILURE — something failed and it's not saying what. an otherwise unspecified failure occurred. it's giving mystery 🕵️
  • 3 — mnemonic NO_SIGNATURE — no acceptable signatures found. nobody signed this, or nobody signed it in a way we accept. 😭
  • 19 — mnemonic MISSING_ARG — missing required argument. you forgot something, bestie 🙈
  • 37 — mnemonic UNSUPPORTED_OPTION — unsupported option. that flag is not it 💀
  • 41 — mnemonic BAD_DATA — invalid data type (like a secret key where CERTS were expected, etc). wrong vibe entirely
  • 59 — mnemonic OUTPUT_EXISTS — output file already exists. it's already there, we're not overwriting
  • 61 — mnemonic MISSING_INPUT — input file does not exist. can't read what isn't there 🦋
  • 69 — mnemonic UNSUPPORTED_SUBCOMMAND — unsupported subcommand. not a thing, sorry
  • 71 — mnemonic UNSUPPORTED_SPECIAL_PREFIX — sopv does not know how to handle the special designator. it looked at the prefix and was like... no thoughts
  • 73 — mnemonic AMBIGUOUS_INPUT — a file with the name of the special designator is present. so like, both things are true at once and it can't pick 👑
Also, ngl, details about warnings or errors may also be emitted to standard error. so keep an eye on stderr, bestie, that's where the tea gets spilled ☕

👑 AUTHOR 👑

This manual page was written by Daniel Kahn Gillmor. Your implementation of sopv is likely written by someone else in alignment with the SOP specification. Please run sopv version to learn more about your implementation. 🫶

🌈 SEE ALSO 🌈

and that's the whole page, bestie 💅 you're now officially fluent in sopv. this was sopv version 1.1, dated March 2025, and yes it's the SOPV(1) page — go forth and verify things. slay 💖✨

📦 where this page comes from