1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
sopv(1) -- 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][semver].
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.
## SEE ALSO
sopv-version(1),
sopv-verify(1),
sopv-inline-verify(1),
[Stateless OpenPGP Command Line Interface][draft-dkg-openpgp-stateless-cli],
[RFC 9580][RFC9580]
|
