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.

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