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 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

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.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

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.