Stateless OpenPGP Command Line Interface

1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

This document uses the term "key" to refer exclusively to OpenPGP Transferable Secret Keys (see Section 10.2 of [RFC9580]).¶

It uses the term "certificate" to refer to OpenPGP Transferable Public Key (see Section 10.1 of [RFC9580]).¶

"Stateless" in "Stateless OpenPGP" means avoiding any sort of persistent and implicit state. The user is responsible for managing all OpenPGP certificates and secret keys themselves, and passing them to sop as needed. The user should also not be concerned that any state could affect the underlying operations.¶

OpenPGP revocations can have "Reason for Revocation" (Section 5.2.3.31 of [RFC9580]), which can be either "soft" or "hard". The set of "soft" reasons is: "Key is superseded" and "Key is retired and no longer used". All other reasons (and revocations that do not state a reason) are "hard" revocations.¶

This document refers to a special verification-only subset of the sop command-line interface as sopv (see Section 3 for more details).¶

1.3. Using sop in a Test Suite

If an OpenPGP implementation provides a sop interface, it can be used to test interoperability (e.g., [OpenPGP-Interoperability-Test-Suite]).¶

Such an interop test suite can, for example, use custom code (not sop) to generate a new OpenPGP object that incorporates new primitives, and feed that object to a stable of sop implementations, to determine whether those implementations can consume the new form.¶

Or, the test suite can drive each sop implementation with a simple input, and observe which cryptographic primitives each implementation chooses to use as it produces output.¶

A simple self-test can be found in Appendix C.¶

1.4. Semantics vs. Wire Format

The semantics of sop are deliberately simple and very high-level compared to the vast complexity and nuance available within the OpenPGP specification. This reflects the perspective of nearly every piece of tooling that relies on OpenPGP to accomplish its task: most toolchains don't care about the specifics, they just want the high-level object security properties.¶

Given this framing, this document generally tries to avoid overconstraining the details of the wire format objects emitted, or what kinds of wire format structures should be acceptable or unacceptable. This allows a test suite to evaluate and contrast the wire format choices made by different implementations in as close to their native configuration as possible. It also makes it easier to promote interoperability by ensuring that the native wire formats emitted by one implementation can be consumed by another, without relying on their choices of wire format being constrained by this draft.¶

Where this draft does identify specific wire format requirements, that might be due to an ambiguity in the existing specifications (which maybe needs fixing elsewhere), or to a bug in this specification that could be improved.¶

3.1. sopv Versioning

The abstract sopv interface is itself versioned using [SEMVER]. The definition of the relevant subcommands and options specified in this document is known as sopv version 1.0.¶

If backward-incompatible changes are made to the sopv subset, the major version number will be increased. If the sopv subset is extended without backward-incompatible changes, the minor version number will be increased.¶

Elements of the CLI relevant to sopv are annotated in this document with the sopv version in which they were introduced.¶

See also Appendix A for enumerated version history.¶

4.1. --debug: emit more verbose output

When the --debug option is present, sop MAY emit implementation-specific debugging information to standard error.¶

A locale-aware, internationalized sop implementation will localize this debugging information.¶

5.1. Meta Subcommands

The subcommands grouped in this section are related to the sop implementation itself.¶

sop version [--backend|--extended|--sop-spec|--sopv]

$ sop version
ExampleSop 0.2.1
$ sop version --backend
LibExamplePGP 3.4.2
$ sop version --extended
ExampleSop 0.2.1
Running on MonkeyScript 4.5
LibExamplePGP 3.4.2
LibExampleCrypto 3.1.1
LibXCompression 4.0.2
See https://pgp.example/sop/ for more information
$ sop version --sop-spec
~draft-dkg-openpgp-stateless-cli-06

This implementation does not handle @FD: special designators for output.
$ sop version --sopv
1.0
$

sop list-profiles SUBCOMMAND

$ sop list-profiles generate-key
default: use the implementer's recommendations
security: higher-security, maybe reduced performance
performance: higher-performance, maybe reduced security
rfc4880: use algorithms from RFC 4880 (alias: compatibility)
$

5.2. Key and Certificate Management Subcommands

The subcommands grouped in this section are primarily intended to manipulate keys and certificates.¶

sop generate-key [--no-armor]
    [--with-key-password=PASSWORD]
    [--profile=PROFILE]
    [--signing-only]
    [--] [USERID...]

$ sop generate-key 'Alice Lovelace <alice@openpgp.example>' > alice.sec
$ head -n1 < alice.sec
-----BEGIN PGP PRIVATE KEY BLOCK-----
$

sop change-key-password [--no-armor]
    [--new-key-password=PASSWORD]
    [--old-key-password=PASSWORD...]

# adding a password to an unlocked key:
$ sop change-key-password --new-key-password=@ENV:keypass \
  < unlocked.key > locked.key
# removing a password:
$ sop change-key-password --old-key-password=@ENV:keypass \
  < locked.key > unlocked.key
# changing a password:
$ sop change-key-password --old-key-password=@ENV:keypass \
  --new-key-password=@ENV:newpass < locked.key > refreshed.key
$

sop revoke-key [--no-armor]
    [--with-key-password=PASSWORD...]

$ sop revoke-key < alice.key > alice-revoked.pgp
$

sop extract-cert [--no-armor]

$ sop extract-cert < alice.sec > alice.pgp
$ head -n1 < alice.pgp
-----BEGIN PGP PUBLIC KEY BLOCK-----
$

sop update-key [--no-armor]
    [--signing-only]
    [--no-added-capabilities]
    [--with-key-password=PASSWORD...]
    [--merge-certs=CERTS...]

$ sop update-key < alice.key > alice-updated.key
$ mv alice-updated.key alice.key
$ sop extract-cert < alice.key > alice.pgp
$

$ sop1 update-key < alice.key | sop2 update-key | \
  sop1 --no-added-capabilities update-key > alice-updated.key
$ mv alice-updated.key alice.key
$ sop1 extract-cert < alice.key > alice.pgp
$

sop merge-certs [--no-armor]
    [--] CERTS [CERTS...]

$ sop merge-certs alice-certified-by-bob.pgp \
  < alice.pgp > alice-updated.pgp
$ mv alice-updated.pgp alice.pgp
$

5.3. User Identity Subcommands

The subcommands in this section handle OpenPGP user identities. OpenPGP certificates contain cryptographic certifications which bind text-based "User IDs" to primary key material, which is in turn cryptographically bound to additional key material.¶

These subcommands are related to the network of cryptographic identity assertions that has traditionally been called the "Web of Trust". Note also the similarity in structure between these subcommands and sop sign (Section 5.4.1) and sop verify (Section 5.4.2)¶

sop certify-userid [--no-armor]
    --userid=USERID
    [--userid=USERID...]
    [--with-key-password=PASSWORD...]
    [--no-require-self-sig]
    [--] KEYS [KEYS...]

$ sop certify-userid \
  --userid="Alice Lovelace <alice@openpgp.example>" \
  bob.key < alice.pgp > alice-signed-by-bob.pgp
$

$ sop certify-userid \
  --userid="Alice Lovelace <lovelace@business.example>" \
  alice.key < alice.pgp > alice-updated.pgp
$ sop update-key --merge-certs alice-updated.pgp \
  < alice.key > alice-updated.key
$ mv alice-updated.key alice.key
$ rm alice-updated.pgp
$ sop extract-cert < alice.key > alice.pgp
$

sop validate-userid
    [--addr-spec-only]
    [--validate-at=DATE]
    [--] USERID CERTS [CERTS...]

$ if sop validate-userid "Alice Lovelace <alice@openpgp.example>" \
  bob.pgp < alice.pgp; then echo Good; fi
Good
$ if sop validate-userid --addr-spec-only "alice@openpgp.example" \
  bob.pgp < alice.pgp; then echo Good; fi
Good
$

5.4. Messaging Subcommands

The subcommands in this section handle OpenPGP messages: encrypting, decrypting, signing, and verifying.¶

sop sign [--no-armor] [--micalg-out=MICALG]
     [--with-key-password=PASSWORD...]
     [--as={binary|text}] [--] KEYS [KEYS...]

$ sop sign --as=text alice.sec < message.txt > message.txt.asc
$ head -n1 < message.txt.asc
-----BEGIN PGP SIGNATURE-----
$

sop verify [--not-before=DATE] [--not-after=DATE]
    [--] SIGNATURES CERTS [CERTS...]

$ sop verify message.txt.asc alice.pgp < message.txt
2019-10-29T18:36:45Z EB85BB5FA33A75E15E944E63F231550C4F47E38E EB85BB5FA33A75E15E944E63F231550C4F47E38E mode:text {"signers": ["alice.pgp"]}
$ echo $?
0
$ tr a-z A-Z < message.txt | sop verify message.txt.asc alice.pgp
$ echo $?
3
$

sop encrypt [--as={binary|text}]
    [--no-armor]
    [--with-password=PASSWORD...]
    [--sign-with=KEYS...]
    [--with-key-password=PASSWORD...]
    [--profile=PROFILE]
    [--session-key-out=SESSIONKEY]
    [--] [CERTS...]

$ sop encrypt --as=text --sign-with=alice.key \
  alice.asc bob.bin < message.eml > encrypted.asc
$ head -n1 encrypted.asc
-----BEGIN PGP MESSAGE-----
$

sop decrypt [--session-key-out=SESSIONKEY]
    [--with-session-key=SESSIONKEY...]
    [--with-password=PASSWORD...]
    [--with-key-password=PASSWORD...]
    [--verifications-out=VERIFICATIONS
     [--verify-with=CERTS...]
     [--verify-not-before=DATE]
     [--verify-not-after=DATE] ]
    [--] [KEYS...]

$ sop decrypt --session-key-out=session.key \
  alice.sec < ciphertext.asc > cleartext.out
$ ls -l ciphertext.asc cleartext.out
-rw-r--r-- 1 user user   321 Oct 28 01:34 ciphertext.asc
-rw-r--r-- 1 user user   285 Oct 28 01:34 cleartext.out
$ sop decrypt --with-session-key=session.key \
  < ciphertext.asc > cleartext2.out
$ diff cleartext.out cleartext2.out
$

sop inline-detach [--no-armor] --signatures-out=SIGNATURES

$ sop inline-detach --signatures-out=Release.pgp < InRelease >Release
$ sop verify Release.pgp archive-keyring.pgp < Release
$

sop inline-verify [--not-before=DATE] [--not-after=DATE]
    [--verifications-out=VERIFICATIONS]
    [--] CERTS [CERTS...]

$ sop inline-verify -- alice.pgp < message.txt
Hello, world!
$ echo $?
0
$ sed s/Hello/Goodbye/ < message.txt | sop inline-verify -- alice.pgp
$ echo $?
3
$

sop inline-sign [--no-armor]
     [--with-key-password=PASSWORD...]
     [--as={binary|text|clearsigned}]
     [--] KEYS [KEYS...]

$ sop inline-sign --as=clearsigned alice.sec \
  < message.txt > message-signed.txt
$ head -n5 < message-signed.txt
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

This is the message.
-----BEGIN PGP SIGNATURE-----
$

5.5. Transport Subcommands

The commands in this section handle manipulating OpenPGP objects for transport: armoring and dearmoring for 7-bit cleanness and compactness, respectively.¶

sop armor

$ sop armor < bob.bin > bob.pgp
$ head -n1 bob.pgp
-----BEGIN PGP PUBLIC KEY BLOCK-----
$

sop dearmor

$ sop dearmor < message.txt.asc > message.txt.sig
$

6.1. DATE

An ISO-8601 formatted timestamp with time zone, or the special value now to indicate the current system time.¶

Examples:¶

• now¶

• 2019-10-29T12:11:04+00:00¶

• 2019-10-24T23:48:29Z¶

• 20191029T121104Z¶

In some cases where used to specify lower and upper boundaries, a DATE value can be set to - to indicate "no time limit".¶

A flexible implementation of sop MAY accept date inputs in other unambiguous forms.¶

Note that whenever sop emits a timestamp (e.g., in Section 7.10) it MUST produce only a UTC-based ISO-8601 compliant representation with a resolution of one second, using the literal Z suffix to indicate timezone.¶

6.2. USERID

This is an arbitrary UTF-8 string (Section 11.7). By convention, most User IDs are of the form Display Name <email.address@example.com>, but they do not need to be.¶

By internal policy, an implementation MAY reject a USERID if there are certain UTF-8 strings it declines to work with as a User ID. For example, an implementation may reject the empty string, or a string with characters in it that it considers problematic. Of course, refusing to create a particular User ID does not prevent an implementation from encountering such a User ID in its input.¶

6.3. SUBCOMMAND

This is an ASCII string that matches the name of one of the subcommands listed in Section 5.¶

6.4. PROFILE

Some sop subcommands can accept a --profile option, which takes as an argument the name of a profile.¶

A profile name is a UTF-8 string that has no whitespace in it.¶

Which profiles are available depends on the sop implementation.¶

Similar to OpenPGP Notation names, profile names are divided into two namespaces: the IETF namespace and the user namespace. A profile name in the user namespace ends with the @ character (0x40) followed by a DNS domain name. A profile name in the IETF namespace does not have an @ character.¶

A profile name in the user space is owned and controlled by the owner of the domain in the suffix. A sop implementation that implements a user profile but does not own the domain in question SHOULD hew as closely as possible to the semantics described by the owner of the domain.¶

A profile name in the IETF namespace that begins with the string rfc should have semantics that hew as closely as possible to the referenced RFC. Similarly, a profile name in the IETF namespace that begins with the string draft- should have semantics that hew as closely as possible to the referenced Internet Draft.¶

The reserved profile name default in the IETF namespace simply refers to the implementation's default choices. It is not mandatory to name the default profile default. The first profile listed in the list-profiles output is considered the default configuration, as specified in Section 7.12.¶

The reserved profile names security, performance, and compatibility refer to the implementation's choices when increased emphasis on security, performance or compatibility is required, respectively. It is not mandatory to name any profile security, performance, or compatibility; in that case, those profile names MUST act as aliases of another profile name. They are also allowed to be aliases of the default profile.¶

Note that this profile mechanism is intended to provide a limited way for an implementation to select among a small set of options that the implementer has vetted and is satisfied with. It is not intended to provide an arbitrary channel for complex configuration, and a sop implementation MUST NOT use it in that way.¶

7.1. Special Designators for Indirect Types

An indirect argument or parameter that starts with "@" (COMMERCIAL AT, U+0040) is not treated as a filename, but is reserved for special handling, based on the prefix that follows the @. We describe two of those prefixes (@ENV: and @FD:) here. A sop implementation that receives such a special designator but does not know how to handle a given prefix in that context MUST fail with UNSUPPORTED_SPECIAL_PREFIX.¶

See Section 11.9 for more details about safe handling of these special designators.¶

7.2. CERTS

One or more OpenPGP certificates (Section 10.1 of [RFC9580]), aka "Transferable Public Key". May be armored (see Section 11.4).¶

Although some existing workflows may prefer to use one CERTS object with multiple certificates in it (a "keyring"), supplying exactly one certificate per CERTS input will make error reporting clearer and easier.¶

If any CERTS input contains secret key material, sop MUST fail with BAD_DATA. This strictness is intended to keep the consumer of the sop interface clear about what material they are dealing with in what locations. This should reduce the consumer's risk of accidentally exposing secret key material where they meant to expose a CERTS object.¶

7.3. KEYS

One or more OpenPGP Transferable Secret Keys (Section 10.2 of [RFC9580]). May be armored (see Section 11.4).¶

Secret key material is often locked with a password to ensure that it cannot be simply copied and reused. If any secret key material is locked with a password and no --with-key-password option is supplied, sop may fail with error KEY_IS_PROTECTED. However, when a cleartext secret key (that is, one not locked with a password) is available, sop should always be able to use it, whether a --with-key-password option is supplied or not.¶

Although some existing workflows may prefer to use one KEYS object with multiple keys in it (a "secret keyring"), supplying exactly one key per KEYS input will make error reporting clearer and easier.¶

7.4. CIPHERTEXT

sop accepts only a restricted subset of the arbitrarily-nested grammar allowed by the OpenPGP Messages definition (Section 10.3 of [RFC9580]).¶

In particular, it accepts and generates only:¶

An OpenPGP message, consisting of a sequence of PKESKs (Section 5.1 of [RFC9580]) and SKESKs (Section 5.3 of [RFC9580]), followed by one SEIPD (Section 5.13 of [RFC9580]).¶

The SEIPD can decrypt into one of two things:¶

• "Maybe Signed Data" (see below), or¶

• Compressed data packet that contains "Maybe Signed Data"¶

"Maybe Signed Data" is a sequence of:¶

• N (zero or more) one-pass signature packets, followed by¶

• zero or more signature packets, followed by¶

• one Literal data packet, followed by¶

• N signature packets (corresponding to the outer one-pass signatures packets)¶

FIXME: does any tool do compression inside signing? Do we need to handle that?¶

May be armored (see Section 11.4).¶

7.5. INLINESIGNED

An inline-signed message may take any one of three different forms:¶

• A binary sequence of OpenPGP packets that matches a subset of the "Signed Message" element in the grammar in Section 10.3 of [RFC9580]¶

• The same sequence of packets, but ASCII-armored (see Section 11.4)¶

• A message using the Cleartext Signature Framework described in Section 7 of [RFC9580]¶

The subset of the packet grammar expected in the first two forms consists of either:¶

• a series of Signature packets followed by a Literal Data packet¶

• a series of One-Pass Signature (OPS) packets, followed by one Literal Data packet, followed by an equal number of Signature packets corresponding to the OPS packets¶

When the message is in the third form (Cleartext Signature Framework), it has the following properties:¶

• The stream SHOULD consist solely of UTF-8 text¶

• Every Signature packet found in the stream SHOULD have Signature Type 0x01 (canonical text document).¶

• It SHOULD NOT contain leading text (before the -----BEGIN PGP SIGNED MESSAGE----- cleartext header) or trailing text (after the -----END PGP SIGNATURE----- armor tail).¶

While some OpenPGP implementations MAY produce more complicated inline signed messages, a sop implementation SHOULD limit itself to producing these straightforward forms.¶

7.6. SIGNATURES

One or more OpenPGP Signature packets. May be armored (see Section 11.4).¶

7.7. SESSIONKEY

This documentation uses the GnuPG defacto ASCII representation:¶

ALGONUM:HEXKEY¶

where ALGONUM is the decimal value associated with the OpenPGP Symmetric Key Algorithms (Section 9.3 of [RFC9580]) and HEXKEY is the hexadecimal representation of the binary key.¶

Example AES-256 session key:¶

9:FCA4BEAF687F48059CACC14FB019125CD57392BAB7037C707835925CBF9F7BCD

A sop implementation SHOULD produce session key data in this format. When consuming such a session key, sop SHOULD be willing to accept either upper or lower case hexadecimal digits, and to gracefully ignore any trailing whitespace.¶

7.8. MICALG

This output-only type indicates the cryptographic digest used when making a signature. It is useful specifically when generating signed PGP/MIME objects, which want a micalg= parameter for the multipart/signed content type as described in Section 5 of [RFC3156].¶

It will typically be a string like pgp-sha512, but in some situations (multiple signatures using different digests) it will be the empty string. If the user of sop is assembling a PGP/MIME signed object, and the MICALG output is the empty string, the user should omit the micalg= parameter entirely.¶

7.9. PASSWORD

This input-only is expected to be a UTF-8 string (Section 11.7), but for sop decrypt, any bytestring that the user supplies will be accepted. Note the details in sop encrypt and sop decrypt about trailing whitespace!¶

See also Section 11.8 for more discussion.¶

7.10. VERIFICATIONS

This output-only type consists of one line per successful signature verification. Each line has four structured fields delimited by a single space, followed by a single-line JSON object or arbitrary text to the end of the line.¶

• ISO-8601 UTC datestamp of the signature, to one second precision, using the Z suffix¶

• Fingerprint of the signing key (may be a subkey)¶

• Fingerprint of primary key of signing certificate (if signed by primary key, same as the previous field)¶

• A string describing the mode of the signature, either mode:text or mode:binary¶

• A JSON object or free-form message describing the verification (see Section 7.10.1)¶

Note that while Section 6.1 permits a sop implementation to accept other unambiguous date representations, its date output here MUST be a strict ISO-8601 UTC date timestamp. In particular:¶

• the date and time fields MUST be separated by T, not by whitespace, since whitespace is used as a delimiter¶

• the time MUST be emitted in UTC, with the explicit suffix Z¶

• the time MUST be emitted with one-second precision¶

Example:¶

2019-10-24T23:48:29Z C90E6D36200A1B922A1509E77618196529AE5FF8 C4BC2DDB38CCE96485EBE9C2F20691179038E5C6 mode:binary {"signers": ["dkg.asc"]}

7.11. DATA

Cleartext, arbitrary data. This is either a bytestream or UTF-8 text.¶

It MUST only be UTF-8 text in the case of input supplied to sop sign --as=text or sop encrypt --as=text. If sop receives DATA containing non-UTF-8 octets in this case, it will fail (see Section 11.7) with EXPECTED_TEXT.¶

7.12. PROFILELIST

This output-only type consists of simple UTF-8 textual output, with one line per profile. Each line consists of the profile name optionally followed by a colon (0x31), a space (0x20), and a brief human-readable description of the intended semantics of the profile. Each line may be at most 1000 bytes, and no more than 4 profiles may be listed.¶

These limits are intended to force sop implementers to make hard decisions and to keep things simple.¶

The first profile MAY be explicitly named default. If it is not named default, then default is an alias for the first profile listed. No profile after the first listed may be named default.¶

Any of the profiles MAY be explicitly named security, performance, or compatibility. If none of the listed profiles have (some of) these names, the profiles of which they are an alias should indicate as much in the human-readable description.¶

See Section 6.4 for more discussion about the namespace and intended semantics of each profile.¶

11.1. One OpenPGP Message at a Time

sop is intended to be a simple tool that operates on one OpenPGP object at a time. It should be composable, if you want to use it to deal with multiple OpenPGP objects.¶

FIXME: discuss what this means for streaming. The stdio interface doesn't necessarily imply streamed output.¶

11.2. Simplified Subset of OpenPGP Message

While the formal grammar for OpenPGP Message is arbitrarily nestable, sop constrains itself to what it sees as a single "layer" (see Section 7.4).¶

This is a deliberate choice, because it is what most consumers expect. Also, if an arbitrarily-nested structure is parsed with a recursive algorithm, this risks a denial of service vulnerability. sop intends to be implementable with a parser that defensively declines to do recursive descent into an OpenPGP Message.¶

Note that an implementation of sop decrypt MAY choose to handle more complex structures, but if it does, it should document the other structures it handles and why it chooses to do so. We can use such documentation to improve future versions of this spec.¶

11.3. Validate Signatures Only from Known Signers

There are generally only a few signers who are relevant for a given OpenPGP message. When verifying signatures, sop expects that the caller can identify those relevant signers ahead of time.¶

11.4. OpenPGP Inputs can be either Binary or ASCII-armored

OpenPGP material on input can be in either ASCII-armored or binary form. This is a deliberate choice because there are typical scenarios where the program can't predict which form will appear. Expecting the caller of sop to detect the form and adjust accordingly seems both redundant and error-prone.¶

The simple way to detect possible ASCII-armoring is to see whether the high bit of the first octet is set: Section 4.2 of [RFC9580] indicates that bit 7 is always one in the first octet of an OpenPGP packet. In standard ASCII-armor, the first character is "-" (HYPHEN-MINUS, U+002D), so the high bit should be cleared.¶

When considering an input as ASCII-armored OpenPGP material, sop MAY reject an input based on any of the following variations (see Section 6.2 of [RFC9580] for precise definitions):¶

• An unknown Armor Header Line¶

• Any text before the Armor Header Line¶

• Malformed lines in the Armor Headers section¶

• Any non-whitespace data after the Armor Tail¶

• Any Radix-64 encoded line with more than 76 characters¶

• Invalid characters in the Radix-64-encoded data¶

• An invalid Armor Checksum¶

• A mismatch between the Armor Header Line and the Armor Tail¶

• More than one ASCII-armored object in the input¶

For robustness, sop SHOULD be willing to ignore whitespace after the Armor Tail.¶

For any plural data type (i.e.,SIGNATURES, CERTS, or KEYS), the unarmored form is trivially concatenatable with another object of the same type (e.g., with Unix's cat utility). But the armored forms are not concatenatable without first dearmoring. To avoid inconsistent behavior, a sop implementation SHOULD reject anything that appears to be a concatenated series of ASCII-armored objects.¶

When considering OpenPGP material as input, regardless of whether it is ASCII-armored or binary, sop SHOULD reject any material that doesn't produce a valid stream of OpenPGP packets. For example, sop SHOULD raise an error if an OpenPGP packet header is malformed, or if there is trailing garbage after the end of a packet.¶

For a given type of OpenPGP input material (i.e., SIGNATURES, CERTS, KEYS, INLINESIGNED, or CIPHERTEXT), sop SHOULD also reject any input that does not conform to the expected packet stream. See Section 7 for the expected packet stream for different types.¶

11.5. Complexities of the Cleartext Signature Framework

sop prefers a detached signature as the baseline form of OpenPGP signature, but provides affordances for dealing with inline-signed messages (see INLINESIGNED, Section 7.5) as well.¶

The most complex form of inline-signed messages is the Cleartext Signature Framework (CSF). Handling the CSF structure requires parsing to delimit the multiple parts of the document, including at least:¶

• any preamble before the message¶

• the inline message header (delimiter line, OpenPGP headers)¶

• the message itself¶

• the divider between the message and the signature (including any OpenPGP headers there)¶

• the signature¶

• the divider that terminates the signature¶

• any suffix after the signature¶

Note also that the preamble or the suffix might be arbitrary text, and might themselves contain OpenPGP messages (whether signatures or otherwise).¶

If the parser that does this split differs in any way from the parser that does the verification, or parts of the message are confused, it would be possible to produce a verification status and an actual signed message that don't correspond to one another.¶

Blurred boundary problems like this can produce ugly attacks similar to those found in [EFAIL].¶

A user of sop that receives an inline-signed message (whether the message uses the CSF or not) can detach the signature from the message with sop inline-detach (see Section 5.4.5).¶

Alternately, the user can send the message through sop inline-verify to confirm required signatures, and then (if signatures are valid) supply its output to the consumer of the signed message.¶

11.6. Reliance on Supplied Certs and Keys

A truly stateless implementation may find that it spends more time validating the internal consistency of certificates and keys than it does on the actual object security operations.¶

For performance reasons, an implementation may choose to ignore validation on certificate and key material supplied to it. The security implications of doing so depend on how the certs and keys are managed outside of sop.¶

11.7. Text is always UTF-8

Various places in this specification require UTF-8 [RFC3629] when encoding text. sop implementations SHOULD NOT consider textual data in any other character encoding.¶

OpenPGP Implementations MUST already handle UTF-8, because various parts of [RFC9580] require it, including:¶

• User ID¶

• Notation name¶

• Reason for revocation¶

• ASCII-armor Comment: header¶

Dealing with messages in other charsets leads to weird security failures like [Charset-Switching], especially when the charset indication is not covered by any sort of cryptographic integrity check. Restricting textual data to UTF-8 universally across the OpenPGP ecosystem eliminates any such risk without losing functionality, since UTF-8 can encode all known characters.¶

11.8. Passwords are Human-Readable

Passwords are generally expected to be human-readable, as they are typically recorded and transmitted as human-visible, human-transferable strings. However, they are used in the OpenPGP protocol as bytestrings, so it is important to ensure that there is a reliable bidirectional mapping between strings and bytes. The maximally robust behavior here is for sop encrypt and sop generate-key (that is, commands that use a password to encrypt) to constrain the choice of passwords to strings that have such a mapping, and for sop decrypt and sop sign (and sop inline-sign, as well assop encrypt when decrypting a signing key; that is, commands that use a password to decrypt) to try multiple plausible versions of any password supplied by PASSWORD.¶

11.9. Be Careful with Special Designators

As documented in Section 7.1, special designators for indirect inputs like @ENV: and @FD: (and indirect outputs using @FD:) warrant some special/cautious handling.¶

For one thing, it's conceivable that the filesystem could contain a file with these literal names. If sop receives an indirect output parameter that starts with an "@" (COMMERCIAL AT, U+0040) it MUST NOT write to the filesystem for that parameter. A sop implementation that receives such a parameter as input MAY test for the presence of such a file in the filesystem and fail with AMBIGUOUS_INPUT to warn the user of the ambiguity and possible confusion.¶

These special designators are likely to be used to pass sensitive data (like secret key material or passwords) so that it doesn't need to touch the filesystem. Given this sensitivity, sop should be careful with such an input, and minimize its leakage to other processes. In particular, sop SHOULD NOT leak any environment variable identified by @ENV: or file descriptor identified by @FD: to any subprocess unless the subprocess specifically needs access to that data.¶

11.10. Nuances for Hardware-backed Secret Key Material

There are a number of limitations and nuances to be aware of for hardware-backed secret key support in this interface. Some sop implementations will simply not support hardware-backed secret key material. Other implementations might support only a single kind of hardware-backing (e.g., an OpenPGP Smartcard [OPENPGP-SMARTCARD] but not a TPM, or vice versa).¶

There is no formally adopted OpenPGP standard for identifying that a given secret key is backed by hardware based on the OpenPGP wire format. [I-D.dkg-openpgp-hardware-secrets] proposes one simple and straightforward approach for how the wire format could cover this use case. This simple mechanism is deliberately agnostic about the specific kind of cryptographic hardware, but it does imply a sort of rough shape of what the interface to the hardware would permit. In particular, it will work best with hardware that has the following properties:¶

• The hardware does specific asymmetric secret key operations, using secret keys that it does not release.¶

• The user can ask the hardware to provide a list of corresponding public key material (or OpenPGP key fingerprints) for any of the secret keys held by the device.¶

• The hardware MAY require the provision of a PIN or password to enable secret key operation, but does not require a PIN or password for the list of public key material.¶

The sop interface does not currently provide for provisioning cryptographic hardware with secret key material, or for changing the PIN or password for the cryptographic hardware. Users of cryptographic hardware need to do provisioning and PIN or password setting outside of sop.¶

If a user has two attached hardware tokens that both hold the same secret key, and they are both password-locked, and they use different passwords, sop offers no way for the user to clearly indicate which password belongs to which device. Some cryptographic hardware is designed to lock the device if the wrong password is entered too many times, so users in this configuration are at risk of accidental lockout. The easiest resolution for this is for the user to detach any duplicate devices before invoking sop.¶

Note that some OpenPGP implementations use the private codepoint ranges in the OpenPGP specification within an OpenPGP Transferable Secret Key (e.g., [GNUPG-SECRET-STUB]) to indicate that the secret key can be found on a smartcard.¶

While hardware-backed secret key operations can be significantly slower than modern computers, and physical affordances like button-presses or NFC tapping can themselves incur delay, it's bad form for an invocation of sop to hang forever. This specification doesn't define a specific maximum allowable delay, but if an implementation calls into a hardware device either for public key listing or for secret key operations, it should not allow the cryptographic hardware to take an arbitrary amount of time to respond.¶

11.11. Statelessness exemptions

While this specification strives to define all operations as stateless implementers MAY, for practical reasons, rely on the global state of the system.¶

For example, the following items constitute a system state but are not considered to violate the stateless rule:¶

• current time¶

Implementers are advised to document which global state items they rely on to help in troubleshooting issues for consumers.¶

12.1. Choosing Between --as=text and --as=binary

A program that invokes sop to generate an OpenPGP signature typically needs to decide whether it is making a text or binary signature.¶

By default, sop will make a binary signature. The caller of sop sign should choose --as=text only when it knows that:¶

• the data being signed is in fact textual, and encoded in UTF-8, and¶

• the signed data might be transmitted to the recipient (the verifier of the signature) over a channel that has the propensity to transform line-endings.¶

Examples of such channels include FTP ([RFC0959]) and SMTP ([RFC5321]).¶

12.2. Special Designators and Unusual Filenames

In some cases, a user of sop might want to pass all the files in a given directory as positional parameters (e.g., a list of CERTS files to test a signature against).¶

If one of the files has a name that starts with --, it might be confused by sop for an option. If one of the files has a name that starts with @, it might be confused by sop as a special designator (Section 7.1).¶

If the user wants to deliberately refer to such an ambiguously-named file in the filesystem, they should prefix the filename with ./ or use an absolute path.¶

Any specific @FD: special designator SHOULD NOT be supplied more than once to an invocation of sop. If a sop invocation sees multiple copies of a specific @FD:n input (e.g., sop sign @FD:3 @FD:3), it MAY fail with MISSING_INPUT even if file descriptor 3 contains a valid KEYS, because the bytestream for the KEYS was consumed by the first argument. Doubling up on the same @FD: for output (e.g., sop decrypt --session-key-out=@FD:3 --verifications-out=@FD:3) also results in an ambiguous data stream.¶

13.1. Signature Verification

In many contexts, an OpenPGP signature is verified to prove the origin and integrity of an underlying object.¶

When sop checks a signature over data (e.g., via sop verify or sop decrypt --verify-with), it MUST NOT consider it to be verified unless all of these conditions are met:¶

• The signature must be made by a signing-capable public key that is present in one of the supplied certificates¶

• The certificate and signing subkey must have been created before or at the signature time¶

• The certificate and signing subkey must not have been expired at the signature time¶

• The certificate and signing subkey must not be revoked with a "hard" revocation¶

• If the certificate or signing subkey is revoked with a "soft" revocation, then the signature time must predate the revocation¶

• The signing subkey must be properly bound to the primary key, and cross-signed¶

• The signature (and any dependent signature, such as the cross-sig or subkey binding signatures) must be made with strong cryptographic algorithms (e.g., not MD5 or a 1024-bit RSA key)¶

• The signature must be of type 0x00 ("Signature of a binary document") or 0x01 ("Signature of a canonical text document"); other signature types are inappropriate for data signatures¶

Implementers MAY also consider other factors in addition to the origin and authenticity, including application-specific information.¶

For example, consider the application domain of checking software updates. If software package Foo version 13.3.2 was signed on 2019-10-04, and the user receives a copy of Foo version 12.4.8 that was signed on 2019-10-16, it may be authentic and have a more recent signature date. But it is not an upgrade (12.4.8 < 13.3.2), and therefore it should not be applied automatically.¶

In such cases, it is critical that the application confirms that the other information verified is also protected by the relevant OpenPGP signature.¶

Signature validity is a complex topic (see for example the discussion at [DISPLAYING-SIGNATURES]), and this documentation cannot list all possible details.¶

13.2. Compression

The interface as currently specified does not allow for control of compression. Compressing and encrypting data that may contain both attacker-supplied material and sensitive material could leak information about the sensitive material (see the CRIME attack).¶

Unless an application knows for sure that no attacker-supplied material is present in the input, it should not compress during encryption.¶

14.1. Object Security vs. Transport Security

OpenPGP offers an object security model, but says little to nothing about how the secured objects get to the relevant parties.¶

When sending or receiving OpenPGP material, the implementer should consider what privacy leakage is implicit with the transport.¶

A.1. sopv Version 1.0

The following subcommands:¶

• sop version¶

• sop verify¶

• sop inline-verify¶

And the following features:¶

• Special designators @FD: and @ENV: as input for CERTS objects¶

• Special designator @FD: as possible output for --verifications-out argument to sopv inline-verify¶

• Multiple certificates in each CERTS object¶

• --not-before and --not-after constraints¶

B.1. Design Choices for Library API

The library is deliberately minimal, with data types and functionality corresponding to the SOP CLI. The interface itself should expose no dependencies beyond libc.¶

All datatypes are opaque structs. Library implementations MUST NOT expose library users to the memory layout of the underlying objects.¶

The library deals with data that is all in RAM, and produces data in RAM. For simplicity, it does not currently expose a streaming interface.¶

It should be fairly straightforward to implement the SOP CLI on top of such a library.¶

B.2. Library Use Patterns

There are two main kinds of data structures: operations (e.g., sop_op_sign and sop_op_verify) and datatypes (e.g., sop_keys and sop_certs).¶

Operation objects are one-shot objects. They are used in the following pattern:¶

• create an operations object (sop_op_*_new)¶

• adjust it to behave in certain ways (e.g., sop_op_sign_use_keys, sop_op_verify_not_before)¶

• execute it (with some specific sop_op_*_execute function)¶

• dispose of it (sop_op_*_free)¶

The library user MUST NOT execute the same operation object more than once. When a single operation object is executed more than once, it should fail with SOP_OPERATION_ALREADY_EXECUTED. FIXME: if a use case arises with a reasonable need to re-execute an already adjusted object, we could extend the API to allow the user to clone an object.¶

Datatype objects are reusable objects. For example, it is fine for a library user to pass the same sop_certs to multiple sop_op_* operation objects, as long as the sop_certs object is not freed before the execution of all the operation objects it has been passed to.¶

Datatype objects are also immutable. Any function which modifies a datatype object always creates a new copy of the object, with the specific change applied. This immutability avoids any ambiguity about what should happen when a datatype object is adjusted after it was passed to an operation object but before it was executed.¶

B.3. libsopv C API Subset

A minimalist library subset that only does OpenPGP signature verification might be called libsopv. This library is useful wherever the use case is just OpenPGP signature verification.¶

Such a library MUST implement the following functions from the C API:¶

• sop_ctx_new¶

• sop_ctx_free¶

• sop_set_log_function¶

• sop_set_log_level¶

• sop_version¶

• sop_version_backend¶

• sop_version_extended¶

• sop_buf_size¶

• sop_buf_data¶

• sop_buf_free¶

• sop_certs_from_bytes¶

• sop_certs_free¶

• sop_sigs_from_bytes¶

• sop_sigs_free¶

• sop_verifications_count¶

• sop_verifications_get_time¶

• sop_verifications_get_mode¶

• sop_verifications_to_text¶

• sop_verifications_free¶

• sop_inlinesigned_from_bytes¶

• sop_op_verify_new¶

• sop_op_verify_not_before¶

• sop_op_verify_not_after¶

• sop_op_verify_add_signers¶

• sop_op_verify_detached_execute¶

• sop_op_verify_inline_execute¶

• sop_op_verify_free¶

This minimal library interface should be sufficient to implement the sopv subset version 1.0 (see Section 3).¶

D.1. setup-sopv-test

#!/bin/sh

# Create a-test environment for sopv: Stateless OpenPGP
# implementation Verification-only subset.  This needs a
# signing-capable SOP implementation to work.

# https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/

# Author: Daniel Kahn Gillmor
# License: CC-0

set -e

SOP=$1

if [ -z "$SOP" ]; then
    cat >&2 <<EOF
Usage: $0 [--clean|SOP]

SOP should refer (either by \$PATH or by absolute path) to an
implementation of the Stateless OpenPGP command-line interface.

https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/

This will build a list of files in the current directory which can be
used with ./test-sopv to confirm support for the sopv subset.

If --clean is provided, destroy the list of files for testing sopv.
EOF
    exit 1
fi

objs() {
   for s in .bin ''; do
       printf "%s\n" alice.cert$s bob.cert$s both.cert$s
       for m in text binary; do
           for u in alice bob both; do
               for o in sig inlinesigned; do
                   printf "%s\n" msg.$m.$u.$o$s
               done
           done
       done
   done
   for u in alice bob both; do
       printf "%s\n" msg.text.$u.csf
   done
   printf "%s\n" msg.text msg.binary alice.key bob.key
}

if [ "$SOP" = --clean ]; then
    rm -f $(objs)
    exit 0
fi

sop() {
    "$SOP" "$@"
}

# use the first two profiles for the keys, reusing the default
# if zero or one exists
profiles=$(sop list-profiles generate-key | cut -f1 -d: && \
               echo default && echo default)
profile_line=1

for uid in alice bob; do
    profile=$(printf "%s\n" "$profiles" | sed -n ${profile_line}p)
    profile_line=$(( $profile_line + 1 ))
    if [ "$profile" = default ]; then
        profile=
    else
        profile=--profile=$profile
    fi
    sop generate-key --signing-only $profile "$uid" \
        > "$uid.key"
    sop extract-cert < "$uid.key" > "$uid.cert"
    sop dearmor < "$uid.cert" > "$uid.cert.bin"
done

cat alice.cert.bin bob.cert.bin > both.cert.bin
sop armor < both.cert.bin > both.cert

cat > msg.text <<EOF
This is the signed message for the sopv test suite.

It should test the following things:

- Messages using the cleartext signing framework (CSF)
- Text-based signatures (armored and non-armored)
- Binary data signatures (armored and non-armored)
- Multiple certificates per CERTS or INLINESIGNED
- Unknown signatures in a CERTS
- @ENV as CERTS or SIGNATURES input
- @FD as CERTS or SIGNATURES input
- @FD as --verifications-out
- UTF-8 data (💣)
- Armored and non-armored OpenPGP certificates

Please confirm!
EOF

base64 -d > msg.binary <<EOF
AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4v
MDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5f
YFNPUFYgaXMgdGhlIFN0YXRlbGVzcyBPcGVuUEdQIFZlcmlmaWNhdGlvbiBTdWJz
ZXTimaVhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ent8fX5/gIGCg4SFhoeIiYqL
jI2Oj5CRkpOUlZaXmJmam5ydnp+goaKjpKWmp6ipqqusra6vsLGys7S1tre4ubq7
vL2+v8DBwsPExcbHyMnKy8zNzs/Q0dLT1NXW19jZ2tvc3d7f4OHi4+Tl5ufo6err
7O3u7/Dx8vP09fb3+Pn6+/z9/v8=
EOF

for signer in alice bob; do
    for form in text binary; do
        sop sign --as=$form $signer.key < msg.$form \
            > msg.$form.$signer.sig
        sop dearmor < msg.$form.$signer.sig \
            > msg.$form.$signer.sig.bin
        sop inline-sign --as=$form $signer.key < msg.$form \
            > msg.$form.$signer.inlinesigned
        sop dearmor < msg.$form.$signer.inlinesigned \
            > msg.$form.$signer.inlinesigned.bin
    done
    sop inline-sign --as=clearsigned $signer.key < msg.text \
        > msg.text.$signer.csf
done

for form in text binary; do
    sop sign --as=$form alice.key bob.key < msg.$form \
        > msg.$form.both.sig
    sop dearmor < msg.$form.both.sig > msg.$form.both.sig.bin
    sop inline-sign --as=$form alice.key bob.key < msg.$form \
        > msg.$form.both.inlinesigned
    sop dearmor < msg.$form.both.inlinesigned \
        > msg.$form.both.inlinesigned.bin
done
sop inline-sign --as=clearsigned alice.key bob.key \
    < msg.text > msg.text.both.csf

if ! ls $(objs) > /dev/null; then
    exit 1
fi

D.2. sopv-test

#!/bin/sh

# Test the Stateless OpenPGP implementation Verification-only subset.

# This needs to be run from within a directory created by the
#  setup-sopv-test script.

# https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/

# Author: Daniel Kahn Gillmor
# License: CC-0

SOPV=$1

if [ -z "$SOPV" ]; then
    cat >&2 <<EOF
Usage: $0 SOPV

SOPV should refer (either by \$PATH or by absolute path) to an
implementation of the Stateless OpenPGP Verification-only subset.
See https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/
EOF
    exit 1
fi

sopv() {
    local suffix=""
    if [ -n "$SIN" ]; then
        suffix=" < $SIN"
    fi
    if [ -n "$SOUT" ]; then
        suffix="$suffix > $SOUT"
    fi
    if [ -n "$FD_3" ]; then
        suffix="$suffix 3< $FD_3"
    fi
    if [ -n "$FD_4" ]; then
        suffix="$suffix 4< $FD_4"
    fi
    if [ -n "$FD_5" ]; then
        suffix="$suffix 5< $FD_5"
    fi
    # FD 9 is used for output, not input
    if [ -n "$FD_9" ]; then
        suffix="$suffix 9> $FD_9"
    fi
    local missing=""
    printf "🔒 [%s %s%s]\n" "$SOPV" "$*" "$suffix"
    if ! ( if [ -n "$SIN" ]; then exec < "$SIN"; fi;
           if [ -n "$SOUT" ]; then exec > "$SOUT"; fi;
           if [ -n "$FD_3" ]; then exec 3< "$FD_3"; fi;
           if [ -n "$FD_4" ]; then exec 4< "$FD_4"; fi;
           if [ -n "$FD_5" ]; then exec 5< "$FD_5"; fi;
           if [ -n "$FD_9" ]; then exec 9> "$FD_9"; fi;
           $SOPV "$@") ; then
        printf "💣 Failed: %s%s\n" "$*" "$suffix"
        rm -f "$SOUT"
        ERRORS="$ERRORS
$*$suffix"
        return 1
    else
        PASSCOUNT=$(( $PASSCOUNT + 1 ))
        return 0
    fi
}

sopv_fail() {
    local suffix=""
    if [ -n "$SIN" ]; then
        suffix=" < $SIN"
    fi
    if [ -n "$SOUT" ]; then
        printf 'ERROR: do not call sopv_fail and expect stdout\n'
        exit 1
    fi
    if [ -n "$FD_3" ]; then
        suffix="$suffix 3< $FD_3"
    fi
    if [ -n "$FD_4" ]; then
        suffix="$suffix 4< $FD_4"
    fi
    if [ -n "$FD_5" ]; then
        suffix="$suffix 5< $FD_5"
    fi
    # FD 9 is used for output, not input
    if [ -n "$FD_9" ]; then
        suffix="$suffix 9> $FD_9"
    fi
    local missing=""
    printf "🔒⚠ [%s %s%s]\n" "$SOPV" "$*" "$suffix"
    if ( if [ -n "$SIN" ]; then exec < "$SIN"; fi;
         if [ -n "$FD_3" ]; then exec 3< "$FD_3"; fi;
         if [ -n "$FD_4" ]; then exec 4< "$FD_4"; fi;
         if [ -n "$FD_5" ]; then exec 5< "$FD_5"; fi;
         if [ -n "$FD_9" ]; then exec 9> "$FD_9"; fi;
         $SOPV "$@" > fail.out); then
        printf >&2 "💣 succeeded when it should have failed: %s%s\n" \
               "$*" "$suffix"
        ERRORS="$ERRORS
! $*$suffix"
    else
        if [ -s fail.out ]; then
            printf >&2 "💣 produced material to stdout: %s%s\n" \
                   "$*" "$suffix"
            sed 's/^/ 💣> /' < fail.out >&2
            ERRORS="$ERRORS
! $*$suffix ⚠PRODUCED OUTPUT⚠"
        else
            PASSCOUNT=$(( $PASSCOUNT + 1 ))
        fi
    fi
    rm -f fail.out
}

compare() {
    local args=""
    if [ "$1" = text -o "$1" = clearsigned ]; then
        args=--ignore-trailing-space
    fi
    comptype="$1"
    shift
    if ! [ -r "$1" -a -r "$2" ]; then
        printf "⛅ skipped %s cmp (missing inputs): %s and %s\n" \
               "$comptype" "$1" "$2"
        SKIPCOUNT=$(( $SKIPCOUNT + 1 ))
        return
    fi
    if diff --unified $args "$1" "$2"; then
        printf "👍 %s and %s match!\n" "$1" "$2"
        PASSCOUNT=$(( $PASSCOUNT + 1 ))
    else
        printf " 💣 %s and %s do not match!\n" "$1" "$2"
        ERRORS="$ERRORS
Mismatch ($*)"
    fi
}

reject_output() {
    for f in "$@"; do
        if [ -s "$f" ]; then
            printf "💣 %s should not exist with content!\n" "$f"
            ERRORS="$ERRORS
Should-not-exist $f"
        else
            PASSCOUNT=$(( $PASSCOUNT + 1 ))
        fi
    done
}

confirm_mode() {
    local foundmode=''
    for m in $(cut -f4 -d\  < "$2"); do
        if [ "$m" != "mode:$1" ]; then
            printf "💣 %s should have mentioned mode:%s, was %s!\n" \
                   "$2" "$1" "$m"
            ERRORS="$ERRORS
VERIFICATIONS-bad-mode $2 (was: $m; wanted mode:$1)"
        else
            foundmode=yes
        fi
    done
    if [ -z "$foundmode" ]; then
            printf "💣 %s had no mode, wanted %s!\n" "$2" "$1"
            ERRORS="$ERRORS
VERIFICATIONS-no-mode $2 (wanted mode:$1)"
    else
        PASSCOUNT=$(( $PASSCOUNT + 1 ))
    fi
}

show_errs() {
    if [ -z "$1" ]; then
        if [ 0 -ne $SKIPCOUNT ]; then
            printf "No errors, %d tests passed.\n"
            printf "but %d tests skipped somehow\n" \
                   $PASSCOUNT $SKIPCOUNT
        else
            printf "No errors! %d tests passed\n" $PASSCOUNT
        fi
    else
        local SKIPMSG=''
        if [ 0 -ne $SKIPCOUNT ]; then
            SKIPMSG=$(printf "%d tests skipped due to prior errors" \
                             $SKIPCOUNT)
        fi
        cat <<EOF

$PASSCOUNT tests passed.
$SKIPMSG

=== ERRORS ===
$1

=== Error summary ===
EOF
        E=$(echo "$1" | grep -v '^$')
        printf "%d Errors:\n" $(echo "$E" | wc -l)
        echo "$E" | sed 's/^! //' | cut -f1 -d\  | sort | uniq -c
    fi
}


ERRORS=""
SKIPCOUNT=0
PASSCOUNT=0

combine() {
    # runners take: sopv|sopv_fail signer cert [cert...]
    local runner=$1
    shift
    $runner sopv alice alice.$cert
    $runner sopv bob bob.$cert
    $runner sopv_fail bob alice.$cert
    $runner sopv_fail alice bob.$cert
    $runner sopv both alice.$cert
    $runner sopv both bob.$cert
    $runner sopv both both.$cert
    $runner sopv alice both.$cert
    $runner sopv bob both.$cert
    $runner sopv alice alice.$cert bob.$cert
    $runner sopv alice bob.$cert alice.$cert
    $runner sopv bob alice.$cert bob.$cert
    $runner sopv bob bob.$cert alice.$cert
    FD_3=alice.$cert $runner sopv alice @FD:3
    FD_3=bob.$cert FD_4=alice.$cert $runner sopv alice @FD:3 @FD:4
    # don't try to test @ENV on non-armored certs
    if [ "$cert" = "cert" ]; then
        SIGNER_CERT=$(cat alice.$cert) $runner sopv \
                   alice @ENV:SIGNER_CERT
    fi
}

detached() {
    local sopv=$1
    shift
    local signer=$1
    shift
    SIN=msg.$form $sopv verify $delim msg.$form.$signer.$sig "$@"
    FD_5=msg.$form.$signer.$sig SIN=msg.$form $sopv verify $delim \
                                @FD:5 "$@"
    # don't try to test @ENV on non-armored signatures
    if [ "$sig" = "sig" ]; then
        SIGNATURE=$(cat msg.$form.$signer.$sig) SIN=msg.$form $sopv \
                 verify $delim @ENV:SIGNATURE "$@"
    fi
}

inlinesigned() {
    local sopv=$1
    shift
    local signer=$1
    shift
    local vout=msg.$form.$signer.$inlmsg.verifs
    rm -f "$vout"
    if [ "$sopv" = sopv ]; then
        if SIN=msg.$form.$signer.$inlmsg \
               SOUT=msg.$form.$signer.$inlmsg.out $sopv \
               inline-verify --verifications-out=$vout \
               $delim "$@" ; then
            confirm_mode "$form" "$vout"
        fi
        if FD_9=$vout.fd SIN=msg.$form.$signer.$inlmsg \
                         SOUT=msg.$form.$signer.$inlmsg.out.fd \
                         $sopv inline-verify \
                         --verifications-out=@FD:9 \
                         $delim "$@" ; then
            confirm_mode "$form" "$vout.fd"
        fi
        compare $form msg.$form msg.$form.$signer.$inlmsg.out
        compare binary msg.$form.$signer.$inlmsg.out \
                msg.$form.$signer.$inlmsg.out.fd
        rm -f msg.$form.$signer.$inlmsg.out $vout \
           msg.$form.$signer.$inlmsg.out.fd $vout.fd

        # inlinesigned msgs can't be used as detached signatures:
        SIN=msg.$form sopv_fail verify $delim \
                      msg.$form.$signer.$inlmsg "$@"

    else
        SIN=msg.$form.$signer.$inlmsg $sopv inline-verify \
                                      --verifications-out=$vout \
                                      $delim "$@"
        FD_9=$vout.fd SIN=msg.$form.$signer.$inlmsg $sopv \
                      inline-verify --verifications-out=@FD:9 \
                      $delim "$@"
        reject_output $vout $vout.fd
    fi
}

sopv version --extended
sopv version --sopv

for delim in '' --; do
    for cert in cert cert.bin; do
        for form in binary text; do
            # test detached signature
            for sig in sig sig.bin; do
                combine detached
            done

            # test inline-signed messages
            for inlmsg in inlinesigned inlinesigned.bin; do
                combine inlinesigned
            done
        done

        # test CSF
        form=text inlmsg=csf combine inlinesigned
    done
done

# FIXME:
#
# - --not-before and --not-after
# - JSON extension to VERIFICATIONS, including "signers" (sopv 1.1)
# - using --argument=foo vs. --argument foo ?
# - review equivalence of VERIFICATIONS
# - confirm failure when --verifications-out already exists
# - passing CERTS where SIGNATURES are expected MUST fail
# - passing KEYS where CERTS are expected MUST fail

show_errs "$ERRORS"

G.1. Substantive Changes between -11 and -12:

• Improvements in POSIX shell tests (including robust sopv test)¶

• Define security, performace, and compatibility profile aliases¶

• Clarify that sop armor ought to be able to armor any output that sop produces¶

• Intro: acknowledge increased attention to key/cert management¶

• Add KEY_CANNOT_CERTIFY error code¶

• Relax guidance on multi-signature operations and --micalg-out¶

• Define sopv 1.1 (with changelog)¶

• Document exceptions to statelessness for system-level state¶

G.2. Substantive Changes between -10 and -11:

• update-key: new key management subcommand¶

• merge-certs: new certificate management subcommand¶

• certify-userid: new User ID certification subcommand¶

• validate-userid: new User ID verification subcommand¶

• Replace references to RFC 4880 with RFC 9580¶

• Set aside error 1 as UNSPECIFIED_FAILURE¶

• Encourage JSON output in tail of VERIFICATIONS lines¶

• Add universal (ignorable) --debug option¶

• Add simple (and incomplete) shell-script test in appendix¶

G.3. Substantive Changes between -09 and -10:

• drop @HARDWARE: special designator in favor of the simple [I-D.dkg-openpgp-hardware-secrets] or other magic¶

• drop hardware-specific C API function¶

• define SemVer-versioned sopv subset of CLI¶

• sop version: add --sopv option¶

• define libsopv subset of C API¶

• explicitly require BAD_DATA failure when KEYS are passed as CERTS¶

G.4. Substantive Changes between -08 and -09:

• enable the use of hardware-backed secret key material via the @HARDWARE: special designator¶

• C API: clarify design goals and usage patterns¶

• C API: major overhaul and normalization:¶

  • allow passthrough "cookie" for logging¶

  • allow NULL return from sop_version_*¶

  • explicitly offer SOP_LOG_NEVER¶

  • use *_from_bytes and *_to_bytes instead of *_import and *_export¶

  • datatype objects are now immutable¶

  • operation objects are one-shot¶

  • always return sop_err, even at a slight cost to C caller ergonomics¶

G.5. Substantive Changes between -07 and -08:

• revoke-key, change-key-password: add --no-armor option¶

• generate-key: should fail on non-UTF-8 USERID¶

• generate-key: acknowledge that implementations MAY reject USERIDs that seem bad¶

• armor: drop --label option¶

• encrypt: add --session-key-out option¶

• ASCII-armored objects should not be concatenated¶

• signature verification should only work for sigtypes 0x00 (binary) and 0x01 (canonical text)¶

• sign: Constrain input when --micalg-out is present for alignment with [RFC3156]¶

• propose simple C API for signing and verification¶

G.6. Substantive Changes between -06 and -07:

• generate-key: add --signing-only option¶

• new key management subcommand: change-key-password¶

• new key management subcommand: revoke-key¶

G.7. Substantive Changes between -05 and -06:

• version: add --sop-spec argument¶

• encrypt: add --profile argument¶

G.8. Substantive Changes between -04 and -05:

• decrypt: change --verify-out to --verifications-out¶

• encrypt: add missing --with-key-password¶

• add the concept of "profiles", use with generate-key¶

• include table of known implementations¶

• VERIFICATIONS can now indicate the type of the signature (mode:text or mode:binary)¶

G.9. Substantive Changes between -03 and -04:

• Reinforce that PASSWORD and SESSIONKEY are indirect data types¶

• encrypt: remove --as=mime option¶

• Handle password-locked secret key material: add --with-key-password options to generate-key, sign, and decrypt.¶

• Introduce INLINESIGNED message type (Section 7.5)¶

• Rename detach-inband-signature-and-message to inline-detach, clarify its possible inputs¶

• Add inline-verify¶

• Add inline-sign¶

G.10. Substantive Changes between -02 and -03:

• Added --micalg-out parameter to sign¶

• Change from KEY to KEYS (permit multiple secret keys in each blob)¶

• New error code: KEY_CANNOT_SIGN¶

• version now has --backend and --extended options¶

G.11. Substantive Changes between -01 and -02:

• Added mnemonics for return codes¶

• decrypt should fail when asked to output to a pre-existing file¶

• Removed superfluous --armor option¶

• Much more specific about what armor --label=auto should do¶

• armor and dearmor are now fully idempotent, but work only well-formed OpenPGP streams¶

• Dropped armor --allow-nested¶

• Specified what encrypt --as= means¶

• New error code: KEY_IS_PROTECTED¶

• Documented expectations around human-readable, human-transferable passwords¶

• New subcommand: detach-inband-signature-and-message¶

• More specific guidance about special designators like @FD: and @ENV:, including new error codes UNSUPPORTED_SPECIAL_PREFIX and AMBIGUOUS_INPUT¶

G.12. Substantive Changes between -00 and -01:

• Changed generate subcommand to generate-key¶

• Changed convert subcommand to extract-cert¶

• Added "Input String Types" section as distinct from indirect I/O¶

• Made implicit arguments potentially explicit (e.g., sop armor --label=auto)¶

• Added --allow-nested to sop armor to make it idempotent by default¶

• Added fingerprint of signing (sub)key to VERIFICATIONS output¶

• Dropped --mode and --session-key arguments for sop encrypt (no plausible use, not needed for interop)¶

• Added --with-session-key argument to sop decrypt to allow for session-key-based decryption¶

• Added examples to each subcommand¶

• More detailed error codes for sop encrypt¶

• Move from CERT to CERTS (each CERTS argument might contain multiple certificates)¶