Merge branch 'liw/conventions' into 'main'

feat: add an appendix with a comparison with gpg

See merge request sequoia-pgp/sq-user-guide!22

1 files changed, 423 insertions, 0 deletions

diff --git a/sq-guide.md b/sq-guide.md
index 5f97060..f4c3cc1 100644
--- a/sq-guide.md
+++ b/sq-guide.md
@@ -1141,6 +1141,429 @@ specifics that have been covered in the rest of the book.
 
 
 
+# Appendix: `gpg` and `sq` compared {.unnumbered}
+
+This appendix compares the GnuPG `gpg` command line tool and the
+Sequoia PGP `sq` tool. These are the main user facing programs in the
+two implementations of OpenPGP. The purpose of the comparison is to
+help adopting `sq` if one already knows `gpg`.
+
+At the time of writing this, `sq` has rather less functionality than
+`gpg` does. Another purpose of this comparison is to list missing
+functionality in `sq` to guide its development.
+
+The list below covers all but the most esoteric of options for `gpg`,
+and points at the corresponding functionality in `sq`, or what the
+Sequoia PGP project intends to do if no such functionality exists. For
+the sake of brevity, the `gpg` option is merely named, not described.
+See the `gpg` documentation for a full description of each option.
+
+Options are classified as follows:
+
+* commands or operations: encrypt, sign, decrypt, verify, etc
+  - for all of these, `sq` already has corresponding functionality.
+* variations on operations
+  - for all of these, `sq` already has corresponding functionality.
+* obsolete, also for `gpg`
+  - `sq` does not have or intend to add corresponding functionality
+* irrelevant for `sq`
+  - `sq` does not have or intend to add corresponding functionality
+* missing functionality from `sq`
+  - `sq` will add this functionality, or at least has not rejected it
+
+Note that "corresponding functionality" may be approximate. The way
+`gpg` interacts with the user and the world is sometimes quite
+different from `sq`, so there is sometimes an impedance mismatch that
+makes a direct 1:1 mapping from one command to the other difficult.
+
+
+## Commands and operations
+
+* `--version`
+  - `sq --version`
+* `--help`
+  - `sq --help`
+  - `sq help`
+* `--sign`
+  - `sq sign`
+* `--clear-sign`
+  - `sq sign --cleartext-signature`
+* `--detach-sign`
+  - `sq sign --detached`
+* `--encrypt`
+  - `sq encrypt`
+* `--symmetric`
+  - `sq encrypt --symmetric`
+* `--decrypt`
+  - `sq decrypt`
+* `--verify`
+  - `sq verify`
+* `--list-keys`, `--list-secret-keys`
+  - `sq keyring list`
+* `--show-keys`
+  - this is like `--list-keys`, but with an external file rather than
+    `gpg`'s internal keyring
+  - `sq keyring list`
+* `--list-packets`
+  - `sq packet dump`
+* `--export`, `--export-secret-keys`, `--export-secret-subkeys`
+  - `sq keyring split`
+* `--delete-keys name`, `--delete-secret-keys name`,
+  `--delete-secret-and-public-key name`
+  - `sq keyring filter --prune-certs`
+* `--import`, `--fast-import`
+  - `sq keyring merge`
+* `--enarmor`
+  - `sq armor`
+* `--dearmor`
+  - `sq dearmor`
+* `--sign-key name`, `--lsign-key name`, `--quick-sign-key`,
+  `--quick-lsign-key`
+  - `sq certify`
+* `--quick-generate-key`, `--quick-gen-key`, `--generate-key`,
+  `--gen-key`, `--full-generate-key`, `--full-gen-key`
+  - `sq key generate`
+
+
+
+## Variations on operations
+
+* `--fingerprint`
+  - `sq` already shows fingerprints in `sq keyring list` and similar
+    commands
+* `--armor`, `--no-armor`
+  - `sq` commands take an `--armor` or `--binary` option if it's
+    relevant.
+* `--output`
+  - `sq` commands take an `--output` option if it's relevant
+* `--import-options`, `--import-filter`, `--export-filter`,
+  `--export-options`
+  - `sq keyring filter`
+* `--with-wkd-hash`
+  - `sq wkd url`
+* `-z`, `--compress-level`, `--bzip2-compress-level`
+  - `sq encrypt --compression`, though it gives less control over
+    compression levels
+* `--keyserver`
+  - `sq keyserver --server`
+  - however, see issue [#648](https://gitlab.com/sequoia-pgp/sequoia/-/issues/648)
+* `--recipient`, `--recipient-file`, `--encrypt-to`,
+  `--no-encrypt-to`,
+* `--local-user`, `-u`
+   - `sq encrypt`
+* `--sig-notation`, `--cert-notation`, `-N`, `--set-notation`
+  - `sq sign --notation`
+  - `sq certify --notation`
+* `--ask-cert-expire`, `--no-ask-cert-expire`, `--default-cert-expire`
+  - `sq certify --expires`
+* `--faked-system-time`
+  - `sq` commands that need this have a corresponding option
+
+
+
+## Obsolete
+
+* `--rebuild-keydb-caches`
+  - this fixes an ancient bug in `gpg`, not relevant to `sq` and
+    unlikely to be useful to `gpg` users, either
+* `--force-mdc`, `--disable-mdc`
+  - obsolete in `gpg`, irrelevant to `sq`
+
+
+
+## Irrelevant
+
+These options make no sense for `sq`.
+
+* `--warranty`
+  - write out the warranty disclaimer; we don't feel this needs to be
+    embedded in the software
+* `--dump-options`
+  - we _could_ add an option to list all subcommands and options, if
+    someone has a use case for it; if so, please open an issue to
+    request it
+* `--store`
+  - Useful mainly for debugging. Not appropriate for a user-facing
+    tool. Developers can write a custom tool.
+* `--multifile`, `--verify-files`, `--encrypt-files`,
+  `--decrypt-files`
+  - these are better done by using a shell or scripting language
+* `--check-signatures`
+  - like `--list-keys`, but includes cryptographic verification of
+    each third-party certification
+  - `gpg` has two options, mainly for performance
+  - `sq` should not need this and would prefer to have both
+    performance and security
+* `--fetch-keys`
+  - `curl` or `wget` or similar tools cover this
+  - it's unnecessary for `sq` to do this
+* `--print-md`, `--print-mds`
+  - covered by `sha256sum` and similar programs
+  - it's unnecessary for `sq` to do this
+* `--gen-random`
+  - this isn't really OpenPGP-related functionality
+  - other tools can do something like this.
+  - it's unnecessary for `sq` to do this
+* `--show-photos`, `--no-show-photos`, `--show-keyring`,
+  `--always-trust`, `--show-notation`, `--no-show-notation`,
+  `--show-policy-url`, `--no-show-policy-url`, `--sig-policy-url`,
+  `--cert-policy-url`, `--set-policy-url`, `--sig-keyserver-url`
+  - these are irrelevant for `sq` and seem to be deprecated for `gpg`
+* `--gpgconf-list`, `--gpgconf-test`
+  - irrelevant to `sq`, which doesn't use or interact with `gpgconf`
+* `--list-gcrypt-config`
+  - `sq` doesn't use `gcrypt`
+* `--list-config`
+  - in gpg this is only useful with the `--with-colons` option, which
+    is not relevant to `sq`'s JSON output
+* `--default-preference-list`, `--default-keyserver-url`,
+  `--default-new-key-algo string`, `--options`, `--no-options`
+  - `sq` lacks a configuration file, so this isn't relevant
+  - if we add a configuration file, we don't need to have these
+    options specifically
+* `--preserve-permissions`
+  - `sq` doesn't need this, as it doesn't overwrite keyrings
+* `--no-expensive-trust-checks`
+  - `sq-wot`, which computes trust checks, is quite fast already
+* `--enable-special-filenames`
+  - we don't have a use for this in `sq`
+  - if you have a use case that needs this, please open an issue
+* `--allow-multiple-messages`, `--no-allow-multiple-messages`
+  - `sq` doesn't want this functionality
+* `--allow-secret-key-import`
+  - `sq` doesn't need this for now, as it handles key rings in a
+    different way from `gpg`
+* `--fast-list-mode`
+  - `sq` doesn't need this; if it ever becomes slow, we'll want to fix
+    that in a way that doesn't require the user to do anything
+* `--no-keyring`
+  - `sq` doesn't have the kind of implicit keyrings `gpg` has
+* `--skip-verify`, `--ignore-crc-error`, `--ignore-mdc-error`,
+`--ignore-time-conflict`, `--ignore-valid-from`
+  - too risky for `sq`
+* `--allow-weak-digest-algos`, `--weak-digest`,
+  `--allow-weak-key-signatures`
+  - not something `sq` wants to support
+* `-i`, `--interactive`
+  - `sq` already requires a `--force` option to overwrite an output
+    file
+* `--enable-large-rsa`, `--disable-large-rsa`, `--enable-dsa2`,
+  `--disable-dsa2`
+  - these are obsolete in `gpg` and irrelevant for `sq`
+* `--photo-viewer`, `--exec-path`
+  - `sq` may get functionality to export User Attributes as photos,
+    but won't be running a program to display the photos
+* `--keyring`, `--secret-keyring`, ``--primary-keyring`
+  - `sq` makes the user specify keyring files explicitly, at least for
+    now
+* `--homedir`
+  - currently irrelevant for `sq`
+  - if and when we add support for a local certificate store we may
+    need to add something like this, but we will do it without
+    conflating many things into one setting
+* `--display-charset`, `--utf8-strings`, `--no-utf8-strings`
+  - `sq` just uses UTF8
+  - much of OpenPGP assumes UTF8
+* `--bzip2-decompress-lowmem`
+  - an internal implementation detail of `gpg` that `sq` has no need
+    to emulate
+* `--mangle-dos-filenames`, `--no-mangle-dos-filenames`
+  - `sq` requires the user to provide filenames
+* `--ask-cert-level`, `--no-ask-cert-level`, `--default-cert-level`
+  - `sq` does not want to implement this functionality
+* `--keyid-format`
+  - `sq` uses one key ID format
+* `--keyserver-options`
+  - not needed for `sq`
+* `--no-sig-cache`
+  - irrelevant for `sq`
+* `--lock-once`, `--lock-multiple`, `--lock-never`
+  - `sq` does not have lockable database, and won't make locking one
+    the user's problem
+* `--exit-on-status-write-error`
+  - if `sq` ever gets something like `status-fd`, it will treat write
+    errors as critical errors without being asked
+  - this is an option in `gpg` for backwards compatibility
+* `--no-random-seed-file`
+  - `sq` doesn't have such a file anyway and doesn't want one
+* `--no-greeting`, `--no-secmem-warning`, `--no-permission-warning`,
+  `--require-secmem`, `--no-require-secmem`
+  - `sq` doesn't need these
+* `--require-cross-certification`, `--no-require-cross-certification`
+  - these are to use ancient certificates, which today are considered
+    malformed
+* `--expert`, `--no-expert`
+  - `sq` doesn't need these
+* `--key-origin`, `--with-key-origin`, `--request-origin`
+  - `sq` does not currently care for this
+  - if you have a use for it, please open issue
+* `--with-icao-spelling`
+  - `sq` does not want this
+* `--with-keygrip`
+  - keygrip is a non-standard fingerprint format for `gpg` only
+  - `sq` does not have a use for this
+* `-t`, `--textmode`, `--no-textmode`
+  - not relevant for `sq`
+* `--force-v3-sigs`, `--no-force-v3-sigs`, `--force-v4-certs`,
+  `--no-force-v4-certs
+  - not relevant for `sq`
+* `--personal-cipher-preferences`, `--personal-digest-preferences`,
+  `--s2k-cipher-algo`, `--s2k-digest-algo`, `--s2k-mode`, `--s2k-count`,
+  `--cipher-algo`, `--digest-algo`, `--compress-algo`,
+  `--cert-digest-algo, `--disable-cipher-algo`,
+  `--disable-pubkey-algo`
+  - `sq` doesn't want this
+* `--personal-compress-preferences`
+  - `sq` has an explicit option to enable compression where relevant
+* `--gnupg`, `--openpgp`, `--rfc4880`, `--rfc4880bis`, `--rfc2440`,
+  `--pgp6`, `--pgp7`, `--pgp8`, `--compliance`
+  - `sq` doesn't need these
+* `-n`, `--dry-run`, `--list-only`
+  - `sq` doesn't have a use for these at this time
+* `--enable-progress-filter`, `--status-fd`, `--status-file`
+  - `sq` doesn't have a progress bar, but if it gets one, it won't try
+    to emulate these options
+* ` --attribute-fd`, `--attribute-file`
+  - not needed for `sq`
+  - maybe implemented as JSON output for `sq packet dump` some day
+* `--emit-version`, `--no-emit-version`
+  - `sq` doesn't have a use for these
+* `--known-notation`
+  - not useful for `sq`
+* `--set-filename`, `--use-embedded-filename`,
+  `--no-use-embedded-filename`
+  - `sq` doesn't want these
+* `--for-your-eyes-only`, `--no-for-your-eyes-only`
+  - `sq` doesn't want these
+* `--default-key`, `--default-recipient`, `--default-recipient-self`,
+  `--no-default-recipient`
+  - this is currently irrelevant, as `sq` make users always specify
+    all keys/certs on the command line explicitly; for programmatic use,
+    that is probably the way to go in the future as well, but for
+    interactive use a way to specify defaults may be useful
+* `-v`, `--verbose`, `--no-verbose`, `-q`, `--quiet`, `--batch`,
+  `--no-batch`, `--yes`, `--no`
+  - irrelevant for `sq` due to how it interacts with the user
+* `--max-output`
+  - `sq` doesn't want this
+* `--fixed-list-mode`
+  - not relevant for `sq`
+* `--legacy-list-mode`
+  - not relevant for `sq`
+* `--with-fingerprint`
+  - not relevant for `sq`
+* `--with-subkey-fingerprint`
+  - not relevant for `sq`
+* `--with-secret`
+  - not relevant for `sq`
+* `--disable-signer-uid`
+  - not relevant for `sq`
+* `--not-dash-escaped`
+  - `sq` doesn't want this
+* `--no-symkey-cache`
+  - not relevant for `sq`
+* `--command-fd`, `--command-file`
+  - `sq` doesn't want this; if the functionality is added, it'll be
+    done in a way that's easier to use correctly
+* `--allow-freeform-uid`, `--no-default-keyring`, `--with-key-data`
+  - not relevant for `sq`
+* `--allow-non-selfsigned-uid`, `--no-allow-non-selfsigned-uid`
+  - `sq` doesn't want this, at least for now
+* `--escape-from-lines`, `--no-escape-from-lines`
+  - `sq` always escapes and does not currently want to make it optional
+* `--throw-keyids`, `--no-throw-keyids`
+  - not relevant for `sq` at this time
+* `--comment`, `--no-comments`
+  - not relevant for `sq` at this time
+* `--use-agent`, `--no-use-agent`, `--gpg-agent-info`,
+  `--agent-program`, `--dirmngr-program`, `--disable-dirmngr`,
+  `--no-autostart`
+  * `sq` does not currently support agents; if it ever add such
+    support, we will design something
+
+
+## Missing functionality from `sq`
+
+* `--locate-keys`, `--locate-external-keys`, `--auto-key-locate`,
+  `--no-auto-key-locate`
+  - `sq` needs this, tentatively called `sq key discover`, see issue
+    [#651](https://gitlab.com/sequoia-pgp/sequoia/-/issues/651)
+* `--export-ssh-key`
+  - `sq` needs this, see issue
+    [#850](https://gitlab.com/sequoia-pgp/sequoia/-/issues/850)
+* `--send-keys`, `--receive-keys`, `--recv-keys`, `--refresh-keys`,
+  `--search-keys`
+  - these are partially implemented as `sq keyserver` subcommands,
+    but more work is needed, partly covered in issue
+    [#651](https://gitlab.com/sequoia-pgp/sequoia/-/issues/651)
+* `--list-signatures`, `--list-sigs`
+  - `sq-wot` and certificate store will be needed for this
+* `--debug-level`, `--debug`, `--debug-all`, `--debug-iolbf`,
+  `--logger-fd`, `--log-file`, `--logger-file`
+  - `sq` should have logging, see issue
+    [#852](https://gitlab.com/sequoia-pgp/sequoia/-/issues/852)
+* `--group`, `--ungroup`, `--no-groups`
+  - `sq` does not have this functionality, but if it wants something
+    like this, it should probably be designed from the ground up
+    rather than merely copy `gpg`
+* `--edit-card`, `--card-edit`, `--card-status`, `--change-pin`,
+  `--limit-card-insert-tries`
+  - these will probably end up in separate, backend specific tools
+* `--update-trustdb`, `--check-trustdb`, `--export-ownertrust`,
+  `--import-ownertrust`, `--tofu-policy`, `--trusted-key`,
+  `--trust-model`, `--trustdb-name`, `--min-cert-level`,
+  `--completes-needed`, `--marginals-needed`, `--tofu-default-policy`,
+  `--max-cert-depth`, `--auto-check-trustdb`,
+  `--no-auto-check-trustdb`
+  - see `sq-wot`
+* `--quick-set-expire` and other options
+  - `sq` needs to be able to edit the expiration time of a key or a
+    subkey
+* `--quick-add-key`
+  - `sq` needs to be able to generate subkeys
+* `--generate-revocation`, `--gen-revoke`,
+`--generate-designated-revocation`, `--desig-revoke`
+  - `sq` needs to be able to generate a new revocation certificate
+* `--no-tty`, `--passphrase-repeat`, `--passphrase-fd`,
+  `--passphrase-file`, `--passphrase`
+  - `sq` needs to gain a way to feed a passphrase to it, without
+    having to emulate a `tty` device
+* `--pinentry-mode`
+  - `sq` may need to add support for something like `pinentry`, though
+    possibly via another implementation
+* `--input-size-hint`
+  - `sq` could do with an optional progress indicator, maybe, for
+    operations that are very slow
+* `--with-colons`, `--list-options`, `--verify-options`
+  - This will be covered [Lars's NLnet project](https://liw.fi/sequoia/sq-nlnet/)
+* `--ask-sig-expire`, `--no-ask-sig-expire`, `--default-sig-expire`
+  - `sq sign` could do with an `--expires` option
+* `--show-session-key`, `--override-session-key string`,
+  `--override-session-key-fd`
+  - `sq` may want to add support for session key escrow some day,
+    though it's not relevant now
+* `--include-key-block`
+  - this may be added to `sq` later if it gets standardized
+* `--hidden-recipient`, `--hidden-recipient-file`,
+  `--hidden-encrypt-to`, `--sender`, `--try-secret-key`,
+  `--try-all-secrets`, `--skip-hidden-recipients`,
+  `--no-skip-hidden-recipients`
+  - `sq` may add this in the future, if there's users in need of it
+* `--edit-key`, `--quick-add-uid user-id new-user-id`,
+  `--quick-revoke-uid user-id user-id-to-revoke`,
+  `--quick-set-primary-uid user-id primary-user-id`,
+  `--change-passphrase user-id`, `--passwd user-id`
+  - `sq` needs to add functionality to all relevant key / certificate
+    editing; some of it exists, but this area needs more detailed
+    review
+  - some of the functionality is or will be in other tools, such as
+    `sq-wot`, and an upcoming `sq-card`
+* `--auto-key-import`, `--no-auto-key-import`, `--auto-key-retrieve`,
+  `--no-auto-key-retrieve`
+  - `sq` may need to add this functionality some day, but it's not one
+    the roadmap for now
+
+
 # Appendix: Switching from GnuPG to Sequoia-PGP {.unnumbered}
 
 This appendix is aimed at people who already know how to use `gpg`,