---
name: "sopv"
section: "1"
platform: "linux"
package: "sopv-doc"
version: "1.1.1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/sopv"
---

# sopv(1)

Verify OpenPGP signatures

## 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)](/sopv-version/1.md) for more information.

- **sopv verify**

  Verify detached OpenPGP signatures over a message. See [sopv-verify(1)](/sopv-verify/1.md) for more information.

- **sopv inline-verify**

  Verify an inline-signed OpenPGP message. See [sopv-inline-verify(1)](/sopv-inline-verify/1.md) 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)](/sopv-version/1.md))

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

## SEE ALSO

[sopv-version(1)](/sopv-version/1.md), [sopv-verify(1)](/sopv-verify/1.md), [sopv-inline-verify(1)](/sopv-inline-verify/1.md), 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*