Provided by: sopv-doc_1.1.0-1_all 
NAME
sopv - Verify OpenPGP signatures
SYNOPSIS
sopv [--debug] subcommand
DESCRIPTION
sopv is the verification-only subset of the OpenPGP Stateless Command Line Interface, also known as
"SOP".
sopv is designed to verify OpenPGP signatures. It can verify detached signatures as well as inline
signatures. The caller indicates which signers are acceptable by supplying a set of OpenPGP certificates.
EXAMPLES
$ sopv version
ExampleSop 2.3.0
$ 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"]}
$ 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"]}
$
To do something only when a detached signature is valid:
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
To do something only when an inline signature is valid:
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.
sopv version
Get version, build, and compatibility information about the sopv implementation. See
sopv-version(1) for more information.
sopv verify
Verify detached OpenPGP signatures over a message. See sopv-verify(1) for more information.
sopv inline-verify
Verify an inline-signed OpenPGP message. See sopv-inline-verify(1) for more information.
COMMON OPTIONS
All sopv subcommands accept this option.
--debug
Emit more detailed output on standard error, if available.
Each subcommand also has its own distinct options and arguments, see the corresponding manual page.
INPUT DATA TYPES
Some sopv subcommands take data types as inputs, either as arguments or on standard input.
DATE Dates are represented directly in ISO-8601-compliant format, in UTC with the Z suffix. 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 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
In some cases, sopv emits a VERIFICATIONS text stream, which contains a concise description of every
valid OpenPGP signature discovered.
Each line in a VERIFICATIONS stream represents a valid signature from an acceptable signer. There are at
least three fixed fields which are separated from one another and the final optional fields by
whitespace.
The fields are, 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 is a JSON object. The 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
Wherever a CERTS or SIGNATURES or VERIFICATIONS object is pointed to on the command line, it is typically
presented as a path to a filename. In addition, sopv should also accept a special designator, which is
any string starting with a @ character.
There are two established kinds of special designator:
@FD:nnn
This means to read from or write to the file descriptor identified numerically by nnn. Note that
this is also a valid argument for --verifications-out in sop inline-verify. It can be used there
to operate sopv on an entirely read-only filesystem.
@ENV:varname
This means to read the value from the environment variable named varname. Note that typically only
text-based data is transmittable in this way; a CERTS argument should be armored, for example.
Note also that this can only be used for input to sopv, not output (as sopv cannot set the values
in its callers' environment).
If you want to refer to a file in the filesystem whose name actually begins with an @ (for example,
@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 (see
sopv-version(1))
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.
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.
RETURN CODES
sopv indicates success by returning 0.
A failure is indicated by returning any non-zero return code, often using values from the following
table.
┌───────┬────────────────────────────┬───────────────────────────────────────────────────────────┐
│ Value │ Mnemonic │ Meaning │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 0 │ OK │ Success │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 1 │ UNSPECIFIED_FAILURE │ An otherwise unspecified failure occurred │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 3 │ NO_SIGNATURE │ No acceptable signatures found │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 19 │ MISSING_ARG │ Missing required argument │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 37 │ UNSUPPORTED_OPTION │ Unsupported option │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 41 │ BAD_DATA │ Invalid data type (secret key where CERTS expected, etc) │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 59 │ OUTPUT_EXISTS │ Output file already exists │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 61 │ MISSING_INPUT │ Input file does not exist │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 69 │ UNSUPPORTED_SUBCOMMAND │ Unsupported subcommand │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 71 │ UNSUPPORTED_SPECIAL_PREFIX │ sopv does not know how to handle the special designator │
├───────┼────────────────────────────┼───────────────────────────────────────────────────────────┤
│ 73 │ AMBIGUOUS_INPUT │ A file with the name of the special designator is present │
└───────┴────────────────────────────┴───────────────────────────────────────────────────────────┘
Details about warnings or errors may also be emitted to standard error.
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
sopv-version(1), sopv-verify(1), sopv-inline-verify(1), Stateless OpenPGP Command Line Interface
https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/, RFC 9580
https://www.rfc-editor.org/rfc/rfc9580.html
sopv 1.1 February 2025 SOPV(1)