From 2889a70c102271a1b6ff529bafb6748c4e773014 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Mon, 29 Sep 2014 11:28:55 +0200 Subject: [PATCH] doc: Cleanup gpg.texi. -- We don't need the gpgone and gpgtwoone macros anymore. --- doc/Makefile.am | 2 +- doc/gpg.texi | 338 ++---------------------------------------------- 2 files changed, 14 insertions(+), 326 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index a31f25706..9fd9f6b25 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -46,7 +46,7 @@ DISTCLEANFILES = yat2m yat2m-stamp.tmp yat2m-stamp $(myman_pages) AM_MAKEINFOFLAGS = -I $(srcdir) --css-include=$(srcdir)/texi.css -D gpgone YAT2M_OPTIONS = -I $(srcdir) -D gpgone \ - --release "GnuPG @PACKAGE_VERSION@" --source "GNU Privacy Guard" + --release "GnuPG @PACKAGE_VERSION@" --source "GNU Privacy Guard 1.4" yat2m: Makefile yat2m.c $(CC_FOR_BUILD) -o $@ $(srcdir)/yat2m.c diff --git a/doc/gpg.texi b/doc/gpg.texi index ea6851c73..ded69cef1 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -3,11 +3,6 @@ @c This is part of the GnuPG manual. @c For copying conditions, see the file gnupg.texi. -@c Note that we use this texinfo file for all versions of GnuPG: 1.4.x, -@c 2.0 and 2.1. The macro "gpgone" controls parts which are only valid -@c for GnuPG 1.4, the macro "gpgtwoone" controls parts which are only -@c valid for GnupG 2.1 and later. - @node Invoking GPG @chapter Invoking GPG @cindex GPG command options @@ -16,19 +11,11 @@ @c Begin algorithm defaults -@ifclear gpgtwoone @set DEFSYMENCALGO CAST5 -@end ifclear - -@ifset gpgtwoone -@set DEFSYMENCALGO AES128 -@end ifset @c End algorithm defaults -@c Begin GnuPG 1.x specific stuff -@ifset gpgone @macro gpgname gpg @end macro @@ -49,63 +36,20 @@ gpg .I command .RI [ args ] @end ifset -@end ifset -@c End GnuPG 1.x specific stuff - -@c Begin GnuPG 2 specific stuff -@ifclear gpgone -@macro gpgname -gpg2 -@end macro -@manpage gpg2.1 -@ifset manverb -.B gpg2 -\- OpenPGP encryption and signing tool -@end ifset - -@mansect synopsis -@ifset manverb -.B gpg2 -.RB [ \-\-homedir -.IR dir ] -.RB [ \-\-options -.IR file ] -.RI [ options ] -.I command -.RI [ args ] -@end ifset -@end ifclear -@c Begin GnuPG 2 specific stuff @mansect description -@command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It -is a tool to provide digital encryption and signing services using the -OpenPGP standard. @command{@gpgname} features complete key management and -all bells and whistles you can expect from a decent OpenPGP -implementation. +@command{@gpgname} is the OpenPGP only version of the GNU Privacy +Guard (GnuPG). It is a tool to provide digital encryption and signing +services using the OpenPGP standard. @command{@gpgname} features +complete key management and all bells and whistles you can expect from +a decent OpenPGP implementation. -@ifset gpgone This is the standalone version of @command{gpg}. For desktop use you -should consider using @command{gpg2} @footnote{On some platforms gpg2 is -installed under the name @command{gpg}}. -@end ifset - -@ifclear gpgone -In contrast to the standalone version @command{gpg}, which is more -suited for server and embedded platforms, this version is commonly -installed under the name @command{gpg2} and more targeted to the desktop -as it requires several other modules to be installed. The standalone -version will be kept maintained and it is possible to install both -versions on the same system. If you need to use different configuration -files, you should make use of something like @file{gpg.conf-2} instead -of just @file{gpg.conf}. -@end ifclear +should consider using @command{gpg2} from the GnuPG-2 package +@footnote{On some platforms gpg2 is installed under the name +@command{gpg}}. @manpause -@ifclear gpgone -Documentation for the old standard @command{gpg} is available as a man -page and at @inforef{Top,GnuPG 1,gpg}. -@end ifclear @xref{Option Index}, for an index to @command{@gpgname}'s commands and options. @mancont @@ -300,12 +244,11 @@ Identical to @option{--multifile --decrypt}. @opindex list-keys List all keys from the public keyrings, or just the keys given on the command line. -@ifset gpgone + @option{-k} is slightly different from @option{--list-keys} in that it allows only for one argument and takes the second argument as the keyring to search. This is for command line compatibility with PGP 2 and has been removed in @command{gpg2}. -@end ifset Avoid using the output of this command in scripts or other programs as it is likely to change as GnuPG changes. See @option{--with-colons} for a @@ -323,10 +266,6 @@ secret key is not usable (for example, if it was created via @item --list-sigs @opindex list-sigs Same as @option{--list-keys}, but the signatures are listed too. -@ifclear gpgone -This command has the same effect as -using @option{--list-keys} with @option{--with-sig-list}. -@end ifclear For each signature listed, there are several flags in between the "sig" tag and keyid. These flags give additional information about each @@ -346,10 +285,6 @@ command "tsign"). Same as @option{--list-sigs}, but the signatures are verified. Note that for performance reasons the revocation status of a signing key is not shown. -@ifclear gpgone -This command has the same effect as -using @option{--list-keys} with @option{--with-sig-check}. -@end ifclear The status of the verification is indicated by a flag directly following the "sig" tag (and thus before the flags described above for @@ -358,16 +293,6 @@ successfully verified, a "-" denotes a bad signature and a "%" is used if an error occurred while checking the signature (e.g. a non supported algorithm). -@ifclear gpgone -@item --locate-keys -@opindex locate-keys -Locate the keys given as arguments. This command basically uses the -same algorithm as used when locating keys for encryption or signing and -may thus be used to see what keys @command{@gpgname} might use. In -particular external methods as defined by @option{--auto-key-locate} may -be used to locate a key. Only public keys are listed. -@end ifclear - @item --fingerprint @opindex fingerprint @@ -453,15 +378,8 @@ an additional signing subkey on a dedicated machine and then using this command to export the key without the primary key to the main machine. -@ifset gpgtwoone -GnuPG may ask you to enter the passphrase for the key. This is -required because the internal protection method of the secret key is -different from the one specified by the OpenPGP protocol. -@end ifset -@ifclear gpgtwoone See the option @option{--simple-sk-checksum} if you want to import an exported secret key into ancient OpenPGP implementations. -@end ifclear @item --import @itemx --fast-import @@ -605,33 +523,11 @@ This section explains the main commands for key management @table @gnupgtabopt -@ifset gpgtwoone -@item --quick-gen-key @code{user-id} -@opindex quick-gen-key -This is simple command to generate a standard key with one user id. -In contrast to @option{--gen-key} the key is generated directly -without the need to answer a bunch of prompts. Unless the option -@option{--yes} is given, the key creation will be canceled if the -given user id already exists in the key ring. - -If invoked directly on the console without any special options an -answer to a ``Continue?'' style confirmation prompt is required. In -case the user id already exists in the key ring a second prompt to -force the creation of the key will show up. -@end ifset - @item --gen-key @opindex gen-key Generate a new key pair using teh current default parameters. This is the standard command to create a new key. -@ifset gpgtwoone -@item --full-gen-key -@opindex gen-key -Generate a new key pair with dialogs for all options. This is an -extended version of @option{--gen-key}. - -@end ifset There is also a feature which allows you to create keys in batch mode. See the the manual section ``Unattended key generation'' on how to use this. @@ -957,34 +853,6 @@ Signs a public key with your secret key but marks it as non-exportable. This is a shortcut version of the subcommand "lsign" from @option{--edit-key}. -@ifset gpgtwoone -@item --quick-sign-key @code{fpr} [@code{names}] -@itemx --quick-lsign-key @code{name} -@opindex quick-sign-key -@opindex quick-lsign-key -Directly sign a key from the passphrase without any further user -interaction. The @code{fpr} must be the verified primary fingerprint -of a key in the local keyring. If no @code{names} are given, all -useful user ids are signed; with given [@code{names}] only useful user -ids matching one of theses names are signed. The command -@option{--quick-lsign-key} marks the signatures as non-exportable. If -such a non-exportable signature already exists the -@option{--quick-sign-key} turns it into a exportable signature. - -This command uses reasonable defaults and thus does not provide the -full flexibility of the "sign" subcommand from @option{--edit-key}. -Its intended use is to help unattended key signing by utilizing a list -of verified fingerprints. -@end ifset - -@ifclear gpgone -@item --passwd @var{user_id} -@opindex passwd -Change the passphrase of the secret key belonging to the certificate -specified as @var{user_id}. This is a shortcut for the sub-command -@code{passwd} of the edit key menu. -@end ifclear - @end table @@ -1286,13 +1154,7 @@ use the specified keyring alone, use @option{--keyring} along with @item --secret-keyring @code{file} @opindex secret-keyring -@ifset gpgtwoone -This is an obsolete option and ignored. All secret keys are stored in -the @file{private-keys-v1.d} directory below the GnuPG home directory. -@end ifset -@ifclear gpgtwoone Same as @option{--keyring} but for the secret keyrings. -@end ifclear @item --primary-keyring @code{file} @opindex primary-keyring @@ -1308,31 +1170,24 @@ the filename does not contain a slash, it is assumed to be in the GnuPG home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is not used). -@ifset gpgone @anchor{option --homedir} -@end ifset @include opt-homedir.texi -@ifset gpgone @item --pcsc-driver @code{file} @opindex pcsc-driver Use @code{file} to access the smartcard reader. The current default is `libpcsclite.so.1' for GLIBC based systems, `/System/Library/Frameworks/PCSC.framework/PCSC' for MAC OS X, `winscard.dll' for Windows and `libpcsclite.so' for other systems. -@end ifset -@ifset gpgone @item --disable-ccid @opindex disable-ccid Disable the integrated support for CCID compliant readers. This allows to fall back to one of the other drivers even if the internal CCID driver can handle the reader. Note, that CCID support is only available if libusb was available at build time. -@end ifset -@ifset gpgone @item --reader-port @code{number_or_string} @opindex reader-port This option may be used to specify the port of the card terminal. A @@ -1341,7 +1196,6 @@ devices. The default is 32768 (first USB device). PC/SC or CCID readers might need a string here; run the program in verbose mode to get a list of available readers. The default is then the first reader found. -@end ifset @item --display-charset @code{name} @opindex display-charset @@ -1683,11 +1537,9 @@ are available for all keyserver types, some common options are: "http_proxy" environment variable, if any. -@ifclear gpgtwoone @item max-cert-size When retrieving a key via DNS CERT, only accept keys up to this size. Defaults to 16384 bytes. -@end ifclear @item debug Turn on debug output in the keyserver helper program. Note that the @@ -1696,28 +1548,16 @@ are available for all keyserver types, some common options are: program uses internally (libcurl, openldap, etc). @item check-cert -@ifset gpgtwoone - This option has no more function since GnuPG 2.1. Use the - @code{dirmngr} configuration options instead. -@end ifset -@ifclear gpgtwoone Enable certificate checking if the keyserver presents one (for hkps or ldaps). Defaults to on. -@end ifclear @item ca-cert-file -@ifset gpgtwoone - This option has no more function since GnuPG 2.1. Use the - @code{dirmngr} configuration options instead. -@end ifset -@ifclear gpgtwoone Provide a certificate store to override the system default. Only necessary if check-cert is enabled, and the keyserver is using a certificate that is not present in a system default certificate list. Note that depending on the SSL library that the keyserver helper is built with, this may actually be a directory or a file. -@end ifclear @end table @@ -1735,7 +1575,6 @@ key signer (defaults to 3) @opindex max-cert-depth Maximum depth of a certification chain (default is 5). -@ifclear gpgtwoone @item --simple-sk-checksum @opindex simple-sk-checksum Secret keys are integrity protected by using a SHA-1 checksum. This @@ -1747,7 +1586,6 @@ a security risk. Note that using this option only takes effect when the secret key is encrypted - the simplest way to make this happen is to change the passphrase on the key (even changing it to the same value is acceptable). -@end ifclear @item --no-sig-cache @opindex no-sig-cache @@ -1778,46 +1616,18 @@ process. @option{--no-auto-check-trustdb} disables this option. @item --use-agent @itemx --no-use-agent @opindex use-agent -@ifclear gpgone -This is dummy option. @command{@gpgname} always requires the agent. -@end ifclear -@ifset gpgone Try to use the GnuPG-Agent. With this option, GnuPG first tries to connect to the agent before it asks for a passphrase. @option{--no-use-agent} disables this option. -@end ifset @item --gpg-agent-info @opindex gpg-agent-info -@ifclear gpgone -This is dummy option. It has no effect when used with @command{gpg2}. -@end ifclear -@ifset gpgone Override the value of the environment variable @samp{GPG_AGENT_INFO}. This is only used when @option{--use-agent} has been given. Given that this option is not anymore used by @command{gpg2}, it should be avoided if possible. -@end ifset -@ifclear gpgone -@item --agent-program @var{file} -@opindex agent-program -Specify an agent program to be used for secret key operations. The -default value is the @file{/usr/bin/gpg-agent}. This is only used -as a fallback when the environment variable @code{GPG_AGENT_INFO} is not -set or a running agent cannot be connected. -@end ifclear - -@ifset gpgtwoone -@item --dirmngr-program @var{file} -@opindex dirmngr-program -Specify a dirmngr program to be used for keyserver access. The -default value is @file{/usr/sbin/dirmngr}. This is only used as a -fallback when the environment variable @code{DIRMNGR_INFO} is not set or -a running dirmngr cannot be connected. -@end ifset - @item --lock-once @opindex lock-once Lock the databases the first time a lock is requested @@ -1997,20 +1807,6 @@ Remove all entries from the @option{--group} list. Use @var{name} as the key to sign with. Note that this option overrides @option{--default-key}. -@ifset gpgtwoone -@item --try-secret-key @var{name} -@opindex try-secret-key -For hidden recipients GPG needs to know the keys to use for trial -decryption. The key set with @option{--default-key} is always tried -first, but this is often not sufficient. This option allows to set more -keys to be used for trial decryption. Although any valid user-id -specification may be used for @var{name} it makes sense to use at least -the long keyid to avoid ambiguities. Note that gpg-agent might pop up a -pinentry for a lot keys to do the trial decryption. If you want to stop -all further trial decryption you may use close-window button instead of -the cancel button. -@end ifset - @item --try-all-secrets @opindex try-all-secrets Don't look at the key ID as stored in the message but try all secret @@ -2129,17 +1925,11 @@ opposite meaning. The options are: Include designated revoker information that was marked as "sensitive". Defaults to no. - @c Since GnuPG 2.1 gpg-agent manages the secret key and thus the - @c export-reset-subkey-passwd hack is not anymore justified. Such use - @c cases need to be implemented using a specialized secret key export - @c tool. -@ifclear gpgtwoone @item export-reset-subkey-passwd When using the @option{--export-secret-subkeys} command, this option resets the passphrases for all exported subkeys to empty. This is useful when the exported subkey is to be used on an unattended machine where a passphrase doesn't necessarily make sense. Defaults to no. -@end ifclear @item export-clean Compact (remove all signatures from) user IDs on the key being @@ -2170,37 +1960,12 @@ source distribution. @opindex fixed-list-mode Do not merge primary user ID and primary key in @option{--with-colon} listing mode and print all timestamps as seconds since 1970-01-01. -@ifclear gpgone -Since GnuPG 2.0.10, this mode is always used and thus this option is -obsolete; it does not harm to use it though. -@end ifclear - -@ifset gpgtwoone -@item --legacy-list-mode -@opindex legacy-list-mode -Revert to the pre-2.1 public key list mode. This only affects the -human readable output and not the machine interface -(i.e. @code{--with-colons}). Note that the legacy format does not -allow to convey suitable information for elliptic curves. -@end ifset @item --with-fingerprint @opindex with-fingerprint Same as the command @option{--fingerprint} but changes only the format of the output and may be used together with another command. -@ifset gpgtwoone -@item --with-keygrip -@opindex with-keygrip -Include the keygrip in the key listings. - -@item --with-secret -@opindex with-secret -Include info about the presence of a secret key in public key listings -done with @code{--with-colons}. - -@end ifset - @end table @c ******************************************* @@ -2223,13 +1988,11 @@ platforms that have different line ending conventions (UNIX-like to Mac, Mac to Windows, etc). @option{--no-textmode} disables this option, and is the default. -@ifset gpgone If @option{-t} (but not @option{--textmode}) is used together with armoring and signing, this enables clearsigned messages. This kludge is needed for command-line compatibility with command-line versions of PGP; normally you would use @option{--sign} or @option{--clearsign} to select the type of the signature. -@end ifset @item --force-v3-sigs @itemx --no-force-v3-sigs @@ -2383,16 +2146,9 @@ a message that PGP 2.x will not be able to handle. Note that `PGP available, but the MIT release is a good common baseline. This option implies -@ifset gpgone @option{--rfc1991 --disable-mdc --no-force-v4-certs --escape-from-lines --force-v3-sigs --cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}. -@end ifset -@ifclear gpgone -@option{--rfc1991 --disable-mdc --no-force-v4-certs - --escape-from-lines --force-v3-sigs --allow-weak-digest-algos - --cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}. -@end ifclear It also disables @option{--textmode} when encrypting. This option is deprecated will be removed in GnuPG 2.1. The reason @@ -2493,12 +2249,10 @@ be given in C syntax (e.g. 0x0042). @opindex debug-all Set all useful debugging flags. -@ifset gpgone @item --debug-ccid-driver @opindex debug-ccid-driver Enable debug output from the included CCID driver for smartcards. Note that this option is only available on some system. -@end ifset @item --faked-system-time @var{epoch} @opindex faked-system-time @@ -2749,10 +2503,6 @@ Read the passphrase from file descriptor @code{n}. Only the first line will be read from file descriptor @code{n}. If you use 0 for @code{n}, the passphrase will be read from STDIN. This can only be used if only one passphrase is supplied. -@ifclear gpgone -Note that this passphrase is only used if the option @option{--batch} -has also been given. This is different from @command{gpg}. -@end ifclear @item --passphrase-file @code{file} @opindex passphrase-file @@ -2761,10 +2511,6 @@ be read from file @code{file}. This can only be used if only one passphrase is supplied. Obviously, a passphrase stored in a file is of questionable security if other users can read this file. Don't use this option if you can avoid it. -@ifclear gpgone -Note that this passphrase is only used if the option @option{--batch} -has also been given. This is different from @command{gpg}. -@end ifclear @item --passphrase @code{string} @opindex passphrase @@ -2772,30 +2518,6 @@ Use @code{string} as the passphrase. This can only be used if only one passphrase is supplied. Obviously, this is of very questionable security on a multi-user system. Don't use this option if you can avoid it. -@ifclear gpgone -Note that this passphrase is only used if the option @option{--batch} -has also been given. This is different from @command{gpg}. -@end ifclear - -@ifset gpgtwoone -@item --pinentry-mode @code{mode} -@opindex pinentry-mode -Set the pinentry mode to @code{mode}. Allowed values for @code{mode} -are: -@table @asis - @item default - Use the default of the agent, which is @code{ask}. - @item ask - Force the use of the Pinentry. - @item cancel - Emulate use of Pinentry's cancel button. - @item error - Return a Pinentry error (``No Pinentry''). - @item loopback - Redirect Pinentry queries to the caller. Note that in contrast to - Pinentry the user is not prompted again if he enters a bad password. -@end table -@end ifset @item --command-fd @code{n} @opindex command-fd @@ -2855,14 +2577,6 @@ necessary to get as much data as possible out of the corrupt message. However, be aware that a MDC protection failure may also mean that the message was tampered with intentionally by an attacker. -@ifclear gpgone -@item --allow-weak-digest-algos -@opindex allow-weak-digest-algos -Signatures made with the broken MD5 algorithm are normally rejected -with an ``invalid digest algorithm'' message. This option allows the -verification of signatures made with such weak algorithms. -@end ifclear - @item --no-default-keyring @opindex no-default-keyring Do not add the default keyrings to the list of keyrings. Note that @@ -3026,14 +2740,12 @@ on the configuration file. @table @gnupgtabopt -@ifset gpgone @item --load-extension @code{name} @opindex load-extension Load an extension module. If @code{name} does not contain a slash it is searched for in the directory configured when GnuPG was built (generally "/usr/local/lib/gnupg"). Extensions are not generally useful anymore, and the use of this option is deprecated. -@end ifset @item --show-photos @itemx --no-show-photos @@ -3051,13 +2763,11 @@ Display the keyring name at the head of key listings to show which keyring a given key resides on. This option is deprecated: use @option{--list-options [no-]show-keyring} instead. -@ifset gpgone @item --ctapi-driver @code{file} @opindex ctapi-driver Use @code{file} to access the smartcard reader. The current default is `libtowitoko.so'. Note that the use of this interface is deprecated; it may be removed in future releases. -@end ifset @item --always-trust @opindex always-trust @@ -3113,10 +2823,6 @@ current home directory (@pxref{option --homedir}). Note that on larger installations, it is useful to put predefined files into the directory @file{/etc/skel/.gnupg/} so that newly created users start up with a working configuration. -@ifclear gpgone -For existing users the a small -helper script is provided to create these files (@pxref{addgnupghome}). -@end ifclear For internal purposes @command{@gpgname} creates and maintains a few other files; They all live in in the current home directory (@pxref{option @@ -3130,26 +2836,13 @@ files; They all live in in the current home directory (@pxref{option @item ~/.gnupg/pubring.gpg.lock The lock file for the public keyring. -@ifset gpgtwoone @item ~/.gnupg/pubring.kbx - The public keyring using a different format. This file is sharred - with @command{gpgsm}. You should backup this file. - - @item ~/.gnupg/pubring.kbx.lock - The lock file for @file{pubring.kbx}. -@end ifset + @itemx ~/.gnupg/pubring.kbx.lock + A public keyring and its lock file used by GnuPG versions >= 2. + It is ignored by GnuPG 1.x @item ~/.gnupg/secring.gpg -@ifclear gpgtwoone The secret keyring. You should backup this file. -@end ifclear -@ifset gpgtwoone - A secret keyring as used by GnuPG versions before 2.1. It is not - used by GnuPG 2.1 and later. - - @item ~/.gnupg/.gpg-v21-migrated - File indicating that a migration to GnuPG 2.1 has taken place. -@end ifset @item ~/.gnupg/trustdb.gpg The trust database. There is no need to backup this file; it is better @@ -3195,9 +2888,8 @@ Operation is further controlled by a few environment variables: @item GPG_AGENT_INFO Used to locate the gpg-agent. -@ifset gpgone This is only honored when @option{--use-agent} is set. -@end ifset + The value consists of 3 colon delimited fields: The first is the path to the Unix Domain Socket, the second the PID of the gpg-agent and the protocol version which should be set to 1. When starting the gpg-agent @@ -3611,9 +3303,5 @@ these parameters: @mansect see also @ifset isman @command{gpgv}(1), -@ifclear gpgone -@command{gpgsm}(1), -@command{gpg-agent}(1) -@end ifclear @end ifset @include see-also-note.texi