security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2024-06-06 23:17:47 +02:00
Code Activity

doc: Cleanup gpg.texi.

Browse Source 
--

We don't need the gpgone and gpgtwoone macros anymore.
This commit is contained in:
Werner Koch 2014-09-29 11:28:55 +02:00
parent 3209f270d2
commit 2889a70c10
2 changed files with 14 additions and 326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Makefile.am
View File

@ -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

338
doc/gpg.texi
View File

@ -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