Allow generation of DSA2 keys without --enable-dsa2.
[gnupg.git] / doc / gpg.texi
index 0cc258e..5540ba2 100644 (file)
@@ -1,5 +1,5 @@
-@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-@c               2007 Free Software Foundation, Inc.
+@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
+@c               2008, 2009 Free Software Foundation, Inc.
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
@@ -149,7 +149,7 @@ cannot abbreviate this command.
 @itemx -h
 @opindex help
 Print a usage message summarizing the most useful command line options.
-Not that you cannot abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @item --warranty
 @opindex warranty
@@ -226,8 +226,8 @@ Store only (make a simple RFC1991 literal data packet).
 @item --decrypt
 @itemx -d
 @opindex decrypt
-Decrypt the file given on the command line (or @code{stdin} if no file
-is specified) and write it to stdout (or the file specified with
+Decrypt the file given on the command line (or STDIN if no file
+is specified) and write it to STDOUT (or the file specified with
 @option{--output}). If the decrypted file is signed, the signature is also
 verified. This command differs from the default operation, as it never
 writes to the filename which is included in the file and it rejects
@@ -237,19 +237,19 @@ files which don't begin with an encrypted message.
 @opindex verify
 Assume that the first argument is a signed file or a detached signature
 and verify it without generating any output. With no arguments, the
-signature packet is read from stdin. If only a sigfile is given, it may
+signature packet is read from STDIN. If only a sigfile is given, it may
 be a complete signature or a detached signature, in which case the
 signed stuff is expected in a file without the ".sig" or ".asc"
 extension.  With more than 1 argument, the first should be a detached
 signature and the remaining files are the signed stuff. To read the
-signed stuff from stdin, use @samp{-} as the second filename.  For
+signed stuff from STDIN, use @samp{-} as the second filename.  For
 security reasons a detached signature cannot read the signed material
-from stdin without denoting it in the above way.
+from STDIN without denoting it in the above way.
 
 @item --multifile
 @opindex multifile
 This modifies certain other commands to accept multiple files for
-processing on the command line or read from stdin with each filename on
+processing on the command line or read from STDIN with each filename on
 a separate line. This allows for many files to be processed at
 once. @option{--multifile} may currently be used along with
 @option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that
@@ -394,7 +394,7 @@ removed first. In batch mode the key must be specified by fingerprint.
 @opindex export
 Either export all keys from all keyrings (default keyrings and those
 registered via option @option{--keyring}), or if at least one name is given,
-those of the given name. The new keyring is written to stdout or to the
+those of the given name. The new keyring is written to STDOUT or to the
 file given with option @option{--output}. Use together with
 @option{--armor} to mail those keys.
 
@@ -425,7 +425,7 @@ Import/merge keys. This adds the given keys to the
 keyring. The fast version is currently just a synonym.
 
 There are a few other options which control how this command works.
-Most notable here is the @option{--keyserver-options merge-only} option
+Most notable here is the @option{--import-options merge-only} option
 which does not insert new keys but does only the merging of new
 signatures, user-IDs and subkeys.
 
@@ -487,14 +487,14 @@ a check is needed. To force a run even in batch mode add the option
 
 @item --export-ownertrust
 @opindex export-ownertrust
-Send the ownertrust values to stdout. This is useful for backup purposes
+Send the ownertrust values to STDOUT. This is useful for backup purposes
 as these values are the only ones which can't be re-created from a
 corrupted trust DB.
 
 @item --import-ownertrust
 @opindex import-ownertrust
 Update the trustdb with the ownertrust values stored in @code{files} (or
-stdin if not given); existing values will be overwritten.
+STDIN if not given); existing values will be overwritten.
 
 @item --rebuild-keydb-caches
 @opindex rebuild-keydb-caches
@@ -505,7 +505,7 @@ situations too.
 @item --print-md @code{algo}
 @itemx --print-mds
 @opindex print-md
-Print message digest of algorithm ALGO for all given files or stdin.
+Print message digest of algorithm ALGO for all given files or STDIN.
 With the second form (or a deprecated "*" as algo) digests for all
 available algorithms are printed.
 
@@ -754,13 +754,24 @@ preferred keyserver and signature notations (if any) are shown.
 Set the list of user ID preferences to @code{string} for all (or just
 the selected) user IDs. Calling setpref with no arguments sets the
 preference list to the default (either built-in or set via
-@option{--default-preference-list}), and calling setpref with "none" as
-the argument sets an empty preference list. Use @command{@gpgname
+@option{--default-preference-list}), and calling setpref with "none"
+as the argument sets an empty preference list. Use @command{@gpgname
 --version} to get a list of available algorithms. Note that while you
 can change the preferences on an attribute user ID (aka "photo ID"),
 GnuPG does not select keys via attribute user IDs so these preferences
 will not be used by GnuPG.
 
+When setting preferences, you should list the algorithms in the order
+which you'd like to see them used by someone else when encrypting a
+message to your key.  If you don't include 3DES, it will be
+automatically added at the end.  Note that there are many factors that
+go into choosing an algorithm (for example, your key may not be the
+only recipient), and so the remote OpenPGP application being used to
+send to you may or may not follow your exact chosen order for a given
+message.  It will, however, only choose an algorithm that is present
+on the preference list of every recipient key.  See also the
+INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
+
 @item keyserver
 @opindex keyedit:keyserver
 Set a preferred keyserver for the specified user ID(s). This allows
@@ -946,7 +957,12 @@ Try to be as quiet as possible.
 @opindex batch
 @opindex no-batch
 Use batch mode.  Never ask, do not allow interactive commands.
-@option{--no-batch} disables this option.
+@option{--no-batch} disables this option.  Note that even with a
+filename given on the command line, gpg might still need to read from
+STDIN (in particular if gpg figures that the input is a
+detached signature and no data file has been specified).  Thus if you
+do not want to feed data via STDIN, you should connect STDIN to
+@file{/dev/null}.
 
 @item --no-tty
 @opindex no-tty
@@ -1077,10 +1093,10 @@ validation. This option is only meaningful if pka-lookups is set.
 
 @item --enable-dsa2
 @itemx --disable-dsa2
-Enables new-style DSA keys which (unlike the old style) may be larger
-than 1024 bit and use hashes other than SHA-1 and RIPEMD/160. Note
-that very few programs currently support these keys and signatures
-from them.
+Enable hash truncation for all DSA keys even for old DSA Keys up to
+1024 bit.  This is also the default with @option{--openpgp}.  Note
+that older versions of GnuPG also required this flag to allow the
+generation of DSA larger than 1024 bit.
 
 @item --photo-viewer @code{string}
 This is the command line that should be run to view a photo ID. "%i"
@@ -1093,7 +1109,7 @@ and "%%" for an actual percent sign. If neither %i or %I are present,
 then the photo will be supplied to the viewer on standard input.
 
 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
-stdin". Note that if your image viewer program is not secure, then
+STDIN". Note that if your image viewer program is not secure, then
 executing it from GnuPG does not make it secure.
 
 @item --exec-path @code{string}
@@ -1474,6 +1490,12 @@ Set the proxy to use for HTTP and HKP keyservers.  This overrides the
 @item max-cert-size
 When retrieving a key via DNS CERT, only accept keys up to this size.
 Defaults to 16384 bytes.
+
+@item debug
+Turn on debug output in the keyserver helper program.  Note that the
+details of debug output depends on which keyserver helper program is
+being used, and in turn, on any libraries that the keyserver helper
+program uses internally (libcurl, openldap, etc).
 @end table
 
 @item --completes-needed @code{n}
@@ -1846,6 +1868,10 @@ 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
 
 @item --with-fingerprint
 @opindex with-fingerprint
@@ -1923,7 +1949,7 @@ Set the list of personal digest preferences to @code{string}.  Use
 and use @code{none} to set no preference at all.  This allows the user
 to factor in their own preferred algorithms when algorithms are chosen
 via recipient key preferences.  The most highly ranked digest
-algorithm in this list is algo used when signing without encryption
+algorithm in this list is also used when signing without encryption
 (e.g. @option{--clearsign} or @option{--sign}). The default value is
 SHA-1.
 
@@ -1933,7 +1959,7 @@ Use @command{@gpgname --version} to get a list of available
 algorithms, and use @code{none} to set no preference at all.  This
 allows the user to factor in their own preferred algorithms when
 algorithms are chosen via recipient key preferences.  The most highly
-ranked compression algorithm in this list is algo used when there are
+ranked compression algorithm in this list is also used when there are
 no recipient keys to consider (e.g. @option{--symmetric}).
 
 @item --s2k-cipher-algo @code{name}
@@ -2103,7 +2129,7 @@ Same as @option{--status-fd}, except the status data is written to file
 @code{file}.
 
 @item --logger-fd @code{n}
-Write log output to file descriptor @code{n} and not to stderr.
+Write log output to file descriptor @code{n} and not to STDERR.
 
 @item --log-file @code{file}
 @itemx --logger-file @code{file}
@@ -2260,12 +2286,15 @@ will still get disabled.
 
 @item --throw-keyids
 @itemx --no-throw-keyids
-Do not put the recipient key IDs into encrypted messages. This helps
-to hide the receivers of the message and is a limited countermeasure
-against traffic analysis. On the receiving side, it may slow down the
-decryption process because all available secret keys must be tried.
-@option{--no-throw-keyids} disables this option. This option is essentially
-the same as using @option{--hidden-recipient} for all recipients.
+Do not put the recipient key IDs into encrypted messages. This helps to
+hide the receivers of the message and is a limited countermeasure
+against traffic analysis.@footnote{Using a little social engineering
+anyone who is able to decrypt the message can check whether one of the
+other recipients is the one he suspects.}  On the receiving side, it may
+slow down the decryption process because all available secret keys must
+be tried.  @option{--no-throw-keyids} disables this option. This option
+is essentially the same as using @option{--hidden-recipient} for all
+recipients.
 
 @item --not-dash-escaped
 This option changes the behavior of cleartext signatures
@@ -2292,7 +2321,7 @@ passphrase.  Defaults to 1 repetition.
 @item --passphrase-fd @code{n}
 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
+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}
@@ -2454,11 +2483,15 @@ This is an obsolete option and is not used anywhere.
 
 @item --allow-multiple-messages
 @item --no-allow-multiple-messages
-Allow processing of multiple OpenPGP messages contained in a single
-file or stream.  Some programs that call GPG are not prepared to deal
-with multiple messages being processed together, so this option
-defaults to no.  Note that versions of GPG prior to 1.4.7 always
-allowed multiple messages.
+Allow processing of multiple OpenPGP messages contained in a single file
+or stream.  Some programs that call GPG are not prepared to deal with
+multiple messages being processed together, so this option defaults to
+no.  Note that versions of GPG prior to 1.4.7 always allowed multiple
+messages.  
+
+Warning: Do not use this option unless you need it as a temporary
+workaround!
+
 
 @item --enable-special-filenames
 This options enables a mode in which filenames of the form
@@ -2698,6 +2731,9 @@ make a clear text signature
 @item gpg -sb @code{file}
 make a detached signature
 
+@item gpg -u 0x12345678 -sb @code{file}
+make a detached signature with the key 0x12345678
+
 @item gpg --list-keys @code{user_ID}
 show keys
 
@@ -2746,7 +2782,7 @@ is *very* easy to spy out your passphrase!
 
 If you are going to verify detached signatures, make sure that the
 program knows about it; either give both filenames on the command line
-or use @samp{-} to specify stdin.
+or use @samp{-} to specify STDIN.
 
 @mansect interoperability
 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS