From 17180d6c5e04501ddaa65798209624dbe831fd10 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Mon, 16 May 2022 16:03:42 +0300 Subject: feat: add an appendix with a comparison with gpg Sponsored-by: NLnet Foundation; NGI Assure --- sq-guide.md | 423 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 423 insertions(+) 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`, -- cgit v1.2.1