Preparing a releasegnupg-1.4.6

1 files changed, 2695 insertions, 0 deletions

diff --git a/doc/gpg.texi b/doc/gpg.texi
new file mode 100644
index 000000000..a8e213c95
--- /dev/null
+++ b/doc/gpg.texi
@@ -0,0 +1,2695 @@
+@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
+@c               2006 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@node Invoking GPG
+@chapter Invoking GPG
+@cindex GPG command options
+@cindex command options
+@cindex options, GPG command
+
+@c Begin GnuPG 1.x specific stuff
+@ifset gpgone
+@macro gpgname
+gpg
+@end macro
+@manpage gpg.1
+@ifset manverb
+.B gpg
+\- OpenPGP encryption and signing tool
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  gpg
+.RB [ \-\-homedir
+.IR dir ]
+.RB [ \-\-options
+.IR file ]
+.RI [ options ]  
+.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.
+
+@ifset gpgone
+This is the standalone version of @command{gpg}.  For desktop use you
+should consider using @command{gpg2}.
+@end ifset
+
+@ifclear gpgone
+In contrast to the standalone version @command{gpg}, which is more
+suited for server and embedded platforms, this version is 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
+
+@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
+
+@menu
+* GPG Commands::        List of all commands.
+* GPG Options::         List of all options.
+* GPG Configuration::   Configuration files.
+* GPG Examples::        Some usage examples.
+
+Developer information:
+@c * Unattended Usage::      Using @command{gpg} from other programs.
+@c * GPG Protocol::        The protocol the server mode uses.
+@end menu
+
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  COMMANDS  ****************
+@c ***************            ****************
+@c *******************************************
+@mansect commands
+@node GPG Commands
+@section Commands
+
+Commands are not distinguished from options execpt for the fact that
+only one command is allowed.
+
+@command{@gpgname} may be run with no commands, in which case it will
+perform a reasonable action depending on the type of file it is given
+as input (an encrypted message is decrypted, a signature is verified,
+a file containing keys is listed).
+
+Please remember that option as well as command parsing stops as soon as
+a non-option is encountered, you can explicitly stop parsing by
+using the special option @option{--}.
+
+
+@menu
+* General GPG Commands::        Commands not specific to the functionality.
+* Operational GPG Commands::    Commands to select the type of operation.
+* OpenPGP Key Management::      How to manage your keys.
+@end menu
+
+
+@c *******************************************
+@c **********  GENERAL COMMANDS  *************
+@c *******************************************
+@node General GPG Commands
+@subsection Commands not specific to the function
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information.  Note that you
+cannot abbreviate this command.
+
+@item --help
+@itemx -h
+@opindex help
+Print a usage message summarizing the most useful command line options.
+Not that you cannot abbreviate this command.
+
+@item --warranty
+@opindex warranty
+Print warranty information.
+
+@item --dump-options
+@opindex dump-options
+Print a list of all available options and commands.  Note that you cannot
+abbreviate this command.
+@end table
+
+
+@c *******************************************
+@c ********  OPERATIONAL COMMANDS  ***********
+@c *******************************************
+@node Operational GPG Commands
+@subsection Commands to select the type of operation
+
+
+@table @gnupgtabopt
+
+@item --sign
+@itemx -s
+@opindex sign
+Make a signature. This command may be combined with @option{--encrypt}
+(for a signed and encrypted message), @option{--symmetric} (for a signed
+and symmetrically encrypted message), or @option{--encrypt} and
+@option{--symmetric} together (for a signed message that may be
+decrypted via a secret key or a passphrase).
+
+@item --clearsign
+@opindex clearsign
+Make a clear text signature. The content in a clear text signature is
+readable without any special software. OpenPGP software is only
+needed to verify the signature. Clear text signatures may modify
+end-of-line whitespace for platform independence and are not intended
+to be reversible.
+
+@item --detach-sign
+@itemx -b
+@opindex detach-sign
+Make a detached signature.
+
+@item --encrypt
+@itemx -e
+@opindex encrypt
+Encrypt data. This option may be combined with @option{--sign} (for a
+signed and encrypted message), @option{--symmetric} (for a message that
+may be decrypted via a secret key or a passphrase), or @option{--sign}
+and @option{--symmetric} together (for a signed message that may be
+decrypted via a secret key or a passphrase).
+
+@item --symmetric
+@itemx -c
+@opindex symmetric
+Encrypt with a symmetric cipher using a passphrase. The default
+symmetric cipher used is CAST5, but may be chosen with the
+@option{--cipher-algo} option. This option may be combined with
+@option{--sign} (for a signed and symmetrically encrypted message),
+@option{--encrypt} (for a message that may be decrypted via a secret key
+or a passphrase), or @option{--sign} and @option{--encrypt} together
+(for a signed message that may be decrypted via a secret key or a
+passphrase).
+
+@item --store
+@opindex store
+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
+@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
+files which don't begin with an encrypted message.
+
+@item --verify
+@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
+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
+security reasons a detached signature cannot read the signed material
+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
+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
+@option{--multifile --verify} may not be used with detached signatures.
+
+@item --verify-files
+@opindex verify-files
+Identical to @option{--multifile --verify}.
+
+@item --encrypt-files
+@opindex encrypt-files
+Identical to @option{--multifile --encrypt}.
+
+@item --decrypt-files
+@opindex decrypt-files
+Identical to @option{--multifile --decrypt}.
+
+@item --list-keys
+@itemx -k
+@itemx --list-public-keys
+@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
+machine-parseable key listing command that is appropriate for use in
+scripts and other programs.
+
+@item --list-secret-keys
+@itemx -K
+@opindex list-secret-keys
+List all keys from the secret keyrings, or just the ones given on the
+command line. A @code{#} after the letters @code{sec} means that the
+secret key is not usable (for example, if it was created via
+@option{--export-secret-subkeys}).
+
+@item --list-sigs
+@opindex list-sigs
+Same as @option{--list-keys}, but the signatures are listed too.
+
+For each signature listed, there are several flags in between the "sig"
+tag and keyid. These flags give additional information about each
+signature. From left to right, they are the numbers 1-3 for certificate
+check level (see @option{--ask-cert-level}), "L" for a local or
+non-exportable signature (see @option{--lsign-key}), "R" for a
+nonRevocable signature (see the @option{--edit-key} command "nrsign"),
+"P" for a signature that contains a policy URL (see
+@option{--cert-policy-url}), "N" for a signature that contains a
+notation (see @option{--cert-notation}), "X" for an eXpired signature
+(see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and
+above to indicate trust signature levels (see the @option{--edit-key}
+command "tsign").
+
+@item --check-sigs
+@opindex check-sigs
+Same as @option{--list-sigs}, but the signatures are verified.
+
+@item --fingerprint
+@opindex fingerprint
+List all keys (or the specified ones) along with their
+fingerprints. This is the same output as @option{--list-keys} but with
+the additional output of a line with the fingerprint. May also be
+combined with @option{--list-sigs} or @option{--check-sigs}.  If this
+command is given twice, the fingerprints of all secondary keys are
+listed too.
+
+@item --list-packets
+@opindex list-packets
+List only the sequence of packets. This is mainly
+useful for debugging.
+
+
+@item --card-edit
+@opindex card-edit
+Present a menu to work with a smartcard. The subcommand "help" provides
+an overview on available commands. For a detailed description, please
+see the Card HOWTO at
+http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
+
+@item --card-status
+@opindex card-status
+Show the content of the smart card.
+
+@item --change-pin
+@opindex change-pin
+Present a menu to allow changing the PIN of a smartcard. This
+functionality is also available as the subcommand "passwd" with the
+@option{--card-edit} command.
+
+@item --delete-key @code{name}
+@opindex delete-key
+Remove key from the public keyring. In batch mode either @option{--yes} is
+required or the key must be specified by fingerprint. This is a
+safeguard against accidental deletion of multiple keys.
+
+@item --delete-secret-key @code{name}
+@opindex delete-secret-key
+Remove key from the secret and public keyring. In batch mode the key
+must be specified by fingerprint.
+
+@item --delete-secret-and-public-key @code{name}
+@opindex delete-secret-and-public-key
+Same as @option{--delete-key}, but if a secret key exists, it will be
+removed first. In batch mode the key must be specified by fingerprint.
+
+@item --export
+@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
+file given with option @option{--output}. Use together with
+@option{--armor} to mail those keys.
+
+@item --send-keys @code{key IDs}
+@opindex send-keys
+Similar to @option{--export} but sends the keys to a keyserver.
+Fingerprints may be used instead of key IDs. Option @option{--keyserver}
+must be used to give the name of this keyserver. Don't send your
+complete keyring to a keyserver --- select only those keys which are new
+or changed by you.
+
+@item --export-secret-keys
+@itemx --export-secret-subkeys
+@opindex export-secret-keys
+@opindex export-secret-subkeys
+Same as @option{--export}, but exports the secret keys instead.  This is
+normally not very useful and a security risk.  The second form of the
+command has the special property to render the secret part of the
+primary key useless; this is a GNU extension to OpenPGP and other
+implementations can not be expected to successfully import such a key.
+See the option @option{--simple-sk-checksum} if you want to import such
+an exported key with an older OpenPGP implementation.
+
+@item --import
+@itemx --fast-import
+@opindex import
+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
+which does not insert new keys but does only the merging of new
+signatures, user-IDs and subkeys.
+
+@item --recv-keys @code{key IDs}
+@opindex recv-keys
+Import the keys with the given key IDs from a keyserver. Option
+@option{--keyserver} must be used to give the name of this keyserver.
+
+@item --refresh-keys
+@opindex refresh-keys
+Request updates from a keyserver for keys that already exist on the
+local keyring. This is useful for updating a key with the latest
+signatures, user IDs, etc. Calling this with no arguments will refresh
+the entire keyring. Option @option{--keyserver} must be used to give the
+name of the keyserver for all keys that do not have preferred keyservers
+set (see @option{--keyserver-options honor-keyserver-url}).
+
+@item --search-keys @code{names}
+@opindex search-keys
+Search the keyserver for the given names. Multiple names given here will
+be joined together to create the search string for the keyserver.
+Option @option{--keyserver} must be used to give the name of this
+keyserver.  Keyservers that support different search methods allow using
+the syntax specified in "How to specify a user ID" below. Note that
+different keyserver types support different search methods. Currently
+only LDAP supports them all.
+
+@item --fetch-keys @code{URIs}
+@opindex fetch-keys
+Retrieve keys located at the specified URIs. Note that different
+installations of GnuPG may support different protocols (HTTP, FTP,
+LDAP, etc.)
+
+@item --update-trustdb
+@opindex update-trustdb
+Do trust database maintenance. This command iterates over all keys and
+builds the Web of Trust. This is an interactive command because it may
+have to ask for the "ownertrust" values for keys. The user has to give
+an estimation of how far she trusts the owner of the displayed key to
+correctly certify (sign) other keys. GnuPG only asks for the ownertrust
+value if it has not yet been assigned to a key. Using the
+@option{--edit-key} menu, the assigned value can be changed at any time.
+
+@item --check-trustdb
+@opindex check-trustdb
+Do trust database maintenance without user interaction. From time to
+time the trust database must be updated so that expired keys or
+signatures and the resulting changes in the Web of Trust can be
+tracked. Normally, GnuPG will calculate when this is required and do it
+automatically unless @option{--no-auto-check-trustdb} is set. This
+command can be used to force a trust database check at any time. The
+processing is identical to that of @option{--update-trustdb} but it
+skips keys with a not yet defined "ownertrust".
+
+For use with cron jobs, this command can be used together with
+@option{--batch} in which case the trust database check is done only if
+a check is needed. To force a run even in batch mode add the option
+@option{--yes}.
+
+@item --export-ownertrust
+@opindex export-ownertrust
+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.
+
+@item --rebuild-keydb-caches
+@opindex rebuild-keydb-caches
+When updating from version 1.0.6 to 1.0.7 this command should be used
+to create signature caches in the keyring. It might be handy in other
+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.
+With the second form (or a deprecated "*" as algo) digests for all
+available algorithms are printed.
+
+@item --gen-random @code{0|1|2}
+@opindex gen-random
+Emit @var{count} random bytes of the given quality level. If count is
+not given or zero, an endless sequence of random bytes will be emitted.
+PLEASE, don't use this command unless you know what you are doing; it
+may remove precious entropy from the system!
+
+@item --gen-prime @code{mode}  @code{bits}
+@opindex gen-prime
+Use the source, Luke :-). The output format is still subject to change.
+
+
+@item --enarmor
+@item --dearmor
+@opindex enarmor
+@opindex --enarmor
+Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
+This is a GnuPG extension to OpenPGP and in general not very useful.
+
+@end table
+
+
+@c *******************************************
+@c *******  KEY MANGEMENT COMMANDS  **********
+@c *******************************************
+@node OpenPGP Key Management
+@subsection How to manage your keys
+
+This section explains the main commands for key management
+
+@table @gnupgtabopt
+
+@item --gen-key
+@opindex gen-key
+Generate a new key pair. This command is normally only used
+interactively.
+
+There is an experimental feature which allows you to create keys in
+batch mode. See the file @file{doc/DETAILS} in the source distribution
+on how to use this.
+
+@item --gen-revoke @code{name}
+@opindex gen-revoke
+Generate a revocation certificate for the complete key. To revoke
+a subkey or a signature, use the @option{--edit} command.
+
+@item --desig-revoke @code{name}
+@opindex desig-revoke
+Generate a designated revocation certificate for a key. This allows a
+user (with the permission of the keyholder) to revoke someone else's
+key.
+
+
+@item --edit-key
+@opindex edit-key
+Present a menu which enables you to do most of the key management
+related tasks.  It expects the specification of a key on the command
+line.
+
+@c ******** Begin Edit-key Options **********
+@table @asis
+
+@item sign
+@opindex keyedit:sign
+Make a signature on key of user @code{name} If the key is not yet
+signed by the default user (or the users given with -u), the program
+displays the information of the key again, together with its
+fingerprint and asks whether it should be signed. This question is
+repeated for all users specified with
+-u.
+
+@item lsign
+@opindex keyedit:lsign
+Same as "sign" but the signature is marked as non-exportable and will
+therefore never be used by others. This may be used to make keys
+valid only in the local environment.
+
+@item nrsign
+@opindex keyedit:nrsign
+Same as "sign" but the signature is marked as non-revocable and can
+therefore never be revoked.
+
+@item tsign
+@opindex keyedit:tsign
+Make a trust signature. This is a signature that combines the notions
+of certification (like a regular signature), and trust (like the
+"trust" command). It is generally only useful in distinct communities
+or groups.
+@end table
+
+@c man:.RS
+Note that "l" (for local / non-exportable), "nr" (for non-revocable,
+and "t" (for trust) may be freely mixed and prefixed to "sign" to
+create a signature of any type desired.
+@c man:.RE
+
+@table @asis
+
+@item revsig
+@opindex keyedit:revsig
+Revoke a signature. For every signature which has been generated by
+one of the secret keys, GnuPG asks whether a revocation certificate
+should be generated.
+
+@item trust
+@opindex keyedit:trust
+Change the owner trust value. This updates the
+trust-db immediately and no save is required.
+
+@item disable
+@itemx enable
+@opindex keyedit:disable
+@opindex keyedit:enable
+Disable or enable an entire key. A disabled key can not normally be
+used for encryption.
+
+@item adduid
+@opindex keyedit:adduid
+Create an alternate user id.
+
+@item addphoto
+@opindex keyedit:addphoto
+Create a photographic user id. This will prompt for a JPEG file that
+will be embedded into the user ID. Note that a very large JPEG will make
+for a very large key. Also note that some programs will display your
+JPEG unchanged (GnuPG), and some programs will scale it to fit in a
+dialog box (PGP).
+
+@item deluid
+@opindex keyedit:deluid
+Delete a user id.  Note that it is not possible to retract a user id,
+once it has been send to the public (i.e. to a keyserver).  In that case
+you better use @code{revuid}.
+
+@item delsig
+@opindex keyedit:delsig
+Delete a signature. Note that it is not possible to retract a signature,
+once it has been send to the public (i.e. to a keyserver).  In that case
+you better use @code{revsig}.
+
+@item revuid
+@opindex keyedit:revuid
+Revoke a user id.
+
+@item addkey
+@opindex keyedit:addkey
+Add a subkey to this key.
+
+@item addcardkey
+@opindex keyedit:addcardkey
+Generate a key on a card and add it to this key.
+
+@item keytocard
+@opindex keyedit:keytocard
+Transfer the selected secret key (or the primary key if no key has been
+selected) to a smartcard. The secret key in the keyring will be replaced
+by a stub if the key could be stored successfully on the card and you
+use the save command later. Only certain key types may be transferred to
+the card. A sub menu allows you to select on what card to store the
+key. Note that it is not possible to get that key back from the card -
+if the card gets broken your secret key will be lost unless you have a
+backup somewhere.
+
+@item bkuptocard @code{file}
+@opindex keyedit:bkuptocard
+Restore the given file to a card. This command may be used to restore a
+backup key (as generated during card initialization) to a new card. In
+almost all cases this will be the encryption key. You should use this
+command only with the corresponding public key and make sure that the
+file given as argument is indeed the backup to restore. You should then
+select 2 to restore as encryption key.  You will first be asked to enter
+the passphrase of the backup key and then for the Admin PIN of the card.
+
+@item delkey
+@opindex keyedit:delkey
+Remove a subkey (secondart key). Note that it is not possible to retract
+a subkey, once it has been send to the public (i.e. to a keyserver).  In
+that case you better use @code{revkey}.
+
+@item addrevoker
+@opindex keyedit:addrevoker
+Add a designated revoker. This takes one optional argument:
+"sensitive". If a designated revoker is marked as sensitive, it will not
+be exported by default (see export-options).
+
+@item revkey
+@opindex keyedit:revkey
+Revoke a subkey.
+
+@item expire
+@opindex keyedit:expire
+Change the key expiration time. If a subkey is selected, the
+expiration time of this subkey will be changed. With no selection,
+the key expiration of the primary key is changed.
+
+@item passwd
+@opindex keyedit:passwd
+Change the passphrase of the secret key.
+
+@item primary
+@opindex keyedit:primary
+Flag the current user id as the primary one, removes the primary user
+id flag from all other user ids and sets the timestamp of all affected
+self-signatures one second ahead. Note that setting a photo user ID
+as primary makes it primary over other photo user IDs, and setting a
+regular user ID as primary makes it primary over other regular user
+IDs.
+
+@item uid @code{n}
+@opindex keyedit:uid
+Toggle selection of user id with index @code{n}.
+Use 0 to deselect all.
+
+@item key @code{n}
+@opindex keyedit:key
+Toggle selection of subkey with index @code{n}.
+Use 0 to deselect all.
+
+@item check
+@opindex keyedit:check
+Check all selected user ids.
+
+@item showphoto
+@opindex keyedit:showphoto
+Display the selected photographic user
+id.
+
+@item pref
+@opindex keyedit:pref
+List preferences from the selected user ID. This shows the actual
+preferences, without including any implied preferences.
+
+@item showpref
+@opindex keyedit:showpref
+More verbose preferences listing for the selected user ID. This shows
+the preferences in effect by including the implied preferences of 3DES
+(cipher), SHA-1 (digest), and Uncompressed (compression) if they are
+not already included in the preference list. In addition, the
+preferred keyserver and signature notations (if any) are shown.
+
+@item setpref @code{string}
+@opindex keyedit:setpref
+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
+--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.
+
+@item keyserver
+@opindex keyedit:keyserver
+Set a preferred keyserver for the specified user ID(s). This allows
+other users to know where you prefer they get your key from. See
+@option{--keyserver-options honor-keyserver-url} for more on how this
+works.  Setting a value of "none" removes an existing preferred
+keyserver.
+
+@item notation
+@opindex keyedit:notation
+Set a name=value notation for the specified user ID(s). See
+@option{--cert-notation} for more on how this works. Setting a value of
+"none" removes all notations, setting a notation prefixed with a minus
+sign (-) removes that notation, and setting a notation name (without the
+=value) prefixed with a minus sign removes all notations with that name.
+
+@item toggle
+@opindex keyedit:toggle
+Toggle between public and secret key listing.
+
+@item clean
+@opindex keyedit:clean
+Compact (by removing all signatures except the selfsig) any user ID
+that is no longer usable (e.g. revoked, or expired). Then, remove any
+signatures that are not usable by the trust calculations.
+Specifically, this removes any signature that does not validate, any
+signature that is superseded by a later signature, revoked signatures,
+and signatures issued by keys that are not present on the keyring.
+
+@item minimize
+@opindex keyedit:minimize
+Make the key as small as possible. This removes all signatures from
+each user ID except for the most recent self-signature.
+
+@item cross-certify
+@opindex keyedit:cross-certify
+Add cross-certification signatures to signing subkeys that may not
+currently have them. Cross-certification signatures protect against a
+subtle attack against signing subkeys. See
+@option{--require-cross-certification}.
+
+@item save
+@opindex keyedit:save
+Save all changes to the key rings and quit.
+
+@item quit
+@opindex keyedit:quit
+Quit the program without updating the
+key rings.
+
+@end table
+
+@c man:.RS
+The listing shows you the key with its secondary keys and all user
+ids. Selected keys or user ids are indicated by an asterisk. The trust
+value is displayed with the primary key: the first is the assigned owner
+trust and the second is the calculated trust value. Letters are used for
+the values:
+@c man:.RE
+
+@table @asis
+
+@item -
+No ownertrust assigned / not yet calculated.
+
+@item e
+Trust
+calculation has failed; probably due to an expired key.
+
+@item q
+Not enough information for calculation.
+
+@item n
+Never trust this key.
+
+@item m
+Marginally trusted.
+
+@item f
+Fully trusted.
+
+@item u
+Ultimately trusted.
+@end table
+@c ******** End Edit-key Options **********
+
+@item --sign-key @code{name}
+@opindex sign-key
+Signs a public key with your secret key. This is a shortcut version of
+the subcommand "sign" from @option{--edit}.
+
+@item --lsign-key @code{name}
+@opindex lsign-key
+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}.
+
+
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  OPTIONS   ****************
+@c ***************            ****************
+@c *******************************************
+@mansect options
+@node GPG Options
+@section Option Summary
+
+@command{@gpgname} comes features a bunch of options to control the exact
+behaviour and to change the default configuration.
+
+@menu
+* GPG Configuration Options::   How to change the configuration.
+* GPG Key related Options::     Key related options.
+* GPG Input and Output::        Input and Output.
+* OpenPGP Options::             OpenPGP protocol specific options.
+* GPG Esoteric Options::        Doing things one usually don't want to do.
+@end menu
+
+Long options can be put in an options file (default
+"~/.gnupg/gpg.conf"). Short option names will not work - for example,
+"armor" is a valid option for the options file, while "a" is not. Do not
+write the 2 dashes, but simply the name of the option and any required
+arguments. Lines with a hash ('#') as the first non-white-space
+character are ignored. Commands may be put in this file too, but that is
+not generally useful as the command will execute automatically with
+every execution of gpg.
+
+Please remember that option parsing stops as soon as a non-option is
+encountered, you can explicitly stop parsing by using the special option
+@option{--}.
+
+@c *******************************************
+@c ********  CONFIGURATION OPTIONS  **********
+@c *******************************************
+@node GPG Configuration Options
+@subsection How to change the configuration
+
+These options are used to change the configuraton and are usually found
+in the option file.
+
+@table @gnupgtabopt
+
+@item --default-key @var{name}
+@opindex default-key
+Use @var{name} as the default key to sign with. If this option is not
+used, the default key is the first key found in the secret keyring.
+Note that @option{-u} or @option{--local-user} overrides this option.
+
+@item --default-recipient @var{name}
+@opindex default-recipient
+Use @var{name} as default recipient if option @option{--recipient} is
+not used and don't ask if this is a valid one. @var{name} must be
+non-empty.
+
+@item --default-recipient-self
+@opindex default-recipient-self
+Use the default key as default recipient if option @option{--recipient} is not
+used and don't ask if this is a valid one. The default key is the first
+one from the secret keyring or the one set with @option{--default-key}.
+
+@item --no-default-recipient
+@opindex no-default-recipient
+Reset @option{--default-recipient} and @option{--default-recipient-self}.
+
+@item -v, --verbose
+@opindex verbose
+Give more information during processing. If used
+twice, the input data is listed in detail.
+
+@item --no-verbose
+@opindex no-verbose
+Reset verbose level to 0.
+
+@item -q, --quiet
+@opindex quiet
+Try to be as quiet as possible.
+
+@item --list-options @code{parameters}
+@opindex list-options
+This is a space or comma delimited string that gives options used when
+listing keys and signatures (that is, @option{--list-keys},
+@option{--list-sigs}, @option{--list-public-keys},
+@option{--list-secret-keys}, and the @option{--edit-key} functions).
+Options can be prepended with a @option{no-} (after the two dashes) to
+give the opposite meaning.  The options are:
+
+@table @asis
+
+@item show-photos
+@opindex list-options:show-photos
+Causes @option{--list-keys}, @option{--list-sigs},
+@option{--list-public-keys}, and @option{--list-secret-keys} to display
+any photo IDs attached to the key.  Defaults to no. See also
+@option{--photo-viewer}.
+
+@item show-policy-urls
+@opindex list-options:show-policy-urls
+Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
+listings.  Defaults to no.
+
+@item show-notations
+@itemx show-std-notations
+@itemx show-user-notations
+@opindex list-options:show-notations
+@opindex list-options:show-std-notations
+@opindex list-options:show-user-notations
+Show all, IETF standard, or user-defined signature notations in the
+@option{--list-sigs} or @option{--check-sigs} listings. Defaults to no.
+
+@item show-keyserver-urls
+
+Show any preferred keyserver URL in the @option{--list-sigs} or
+@option{--check-sigs} listings. Defaults to no.
+
+@item show-uid-validity
+Display the calculated validity of user IDs during key listings.
+Defaults to no.
+
+@item show-unusable-uids
+Show revoked and expired user IDs in key listings. Defaults to no.
+
+@item show-unusable-subkeys
+Show revoked and expired subkeys in key listings. Defaults to no.
+
+@item show-keyring
+Display the keyring name at the head of key listings to show which
+keyring a given key resides on. Defaults to no.
+
+@item show-sig-expire
+Show signature expiration dates (if any) during @option{--list-sigs} or
+@option{--check-sigs} listings. Defaults to no.
+
+@item show-sig-subpackets
+Include signature subpackets in the key listing. This option can take an
+optional argument list of the subpackets to list. If no argument is
+passed, list all subpackets. Defaults to no. This option is only
+meaningful when using @option{--with-colons} along with
+@option{--list-sigs} or @option{--check-sigs}.
+@end table
+
+@item --verify-options @code{parameters}
+This is a space or comma delimited string that gives options used when
+verifying signatures. Options can be prepended with a `no-' to give
+the opposite meaning. The options are:
+
+@table @asis
+
+@item show-photos
+Display any photo IDs present on the key that issued the signature.
+Defaults to no. See also @option{--photo-viewer}.
+
+@item show-policy-urls
+Show policy URLs in the signature being verified. Defaults to no.
+
+@item show-notations
+@itemx show-std-notations
+@itemx show-user-notations
+Show all, IETF standard, or user-defined signature notations in the
+signature being verified. Defaults to IETF standard.
+
+@item show-keyserver-urls
+Show any preferred keyserver URL in the signature being verified.
+Defaults to no.
+
+@item show-uid-validity
+Display the calculated validity of the user IDs on the key that issued
+the signature. Defaults to no.
+
+@item show-unusable-uids
+Show revoked and expired user IDs during signature verification.
+Defaults to no.
+
+@item pka-lookups
+Enable PKA lookups to verify sender addresses. Note that PKA is based
+on DNS, and so enabling this option may disclose information on when
+and what signatures are verified or to whom data is encrypted. This
+is similar to the "web bug" described for the auto-key-retrieve
+feature.
+
+@item pka-trust-increase
+Raise the trust in a signature to full if the signature passes PKA
+validation. This option is only meaningful if pka-lookups is set.
+@end table
+
+@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.
+
+@item --photo-viewer @code{string}
+This is the command line that should be run to view a photo ID. "%i"
+will be expanded to a filename containing the photo. "%I" does the
+same, except the file will not be deleted once the viewer exits.
+Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
+for the key fingerprint, "%t" for the extension of the image type
+(e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
+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
+executing it from GnuPG does not make it secure.
+
+@item --exec-path @code{string}
+Sets a list of directories to search for photo viewers and keyserver
+helpers. If not provided, keyserver helpers use the compiled-in
+default directory, and photo viewers use the $PATH environment
+variable.
+Note, that on W32 system this value is ignored when searching for
+keyserver helpers.
+
+@item --keyring @code{file}
+Add @code{file} to the current list of keyrings. If @code{file} begins
+with a tilde and a slash, these are replaced by the $HOME directory. If
+the filename does not contain a slash, it is assumed to be in the GnuPG
+home directory ("~/.gnupg" if @option{--homedir} or $GNUPGHOME is not
+used).
+
+Note that this adds a keyring to the current list. If the intent is to
+use the specified keyring alone, use @option{--keyring} along with
+@option{--no-default-keyring}.
+
+@item --secret-keyring @code{file}
+Same as @option{--keyring} but for the secret keyrings.
+
+@item --primary-keyring @code{file}
+Designate @code{file} as the primary public keyring. This means that
+newly imported keys (via @option{--import} or keyserver
+@option{--recv-from}) will go to this keyring.
+
+@item --trustdb-name @code{file}
+Use @code{file} instead of the default trustdb. If @code{file} begins
+with a tilde and a slash, these are replaced by the $HOME directory. If
+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
+
+
+@item --pcsc-driver @code{file}
+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.
+
+@item --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.
+
+@item --reader-port @code{number_or_string}
+This option may be used to specify the port of the card terminal. A
+value of 0 refers to the first serial device; add 32768 to access USB
+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.
+
+@item --display-charset @code{name}
+Set the name of the native character set. This is used to convert
+some informational strings like user IDs to the proper UTF-8 encoding.
+Note that this has nothing to do with the character set of data to be
+encrypted or signed; GnuPG does not recode user supplied data. If
+this option is not used, the default character set is determined from
+the current locale. A verbosity level of 3 shows the chosen set.
+Valid values for @code{name} are:
+
+@table @asis
+
+@item iso-8859-1
+This is the Latin 1 set.
+
+@item iso-8859-2
+The Latin 2 set.
+
+@item iso-8859-15
+This is currently an alias for
+the Latin 1 set.
+
+@item koi8-r
+The usual Russian set (rfc1489).
+
+@item utf-8
+Bypass all translations and assume
+that the OS uses native UTF-8 encoding.
+@end table
+
+@item --utf8-strings
+@itemx --no-utf8-strings
+Assume that command line arguments are given as UTF8 strings. The
+default (@option{--no-utf8-strings}) is to assume that arguments are
+encoded in the character set as specified by
+@option{--display-charset}. These options affect all following
+arguments. Both options may be used multiple times.
+
+@ifset gpgone
+@anchor{option --options}
+@end ifset
+@item --options @code{file}
+Read options from @code{file} and do not try to read them from the
+default options file in the homedir (see @option{--homedir}). This
+option is ignored if used in an options file.
+
+@item --no-options
+Shortcut for @option{--options /dev/null}. This option is detected
+before an attempt to open an option file.  Using this option will also
+prevent the creation of a @file{~/.gnupg} homedir.
+
+
+
+@item -z @code{n}
+@itemx --compress-level @code{n}
+@itemx --bzip2-compress-level @code{n}
+Set compression level to @code{n} for the ZIP and ZLIB compression
+algorithms. The default is to use the default compression level of zlib
+(normally 6). @option{--bzip2-compress-level} sets the compression level
+for the BZIP2 compression algorithm (defaulting to 6 as well). This is a
+different option from @option{--compress-level} since BZIP2 uses a
+significant amount of memory for each additional compression level.
+@option{-z} sets both. A value of 0 for @code{n} disables compression.
+
+@item --bzip2-decompress-lowmem
+Use a different decompression method for BZIP2 compressed files. This
+alternate method uses a bit more than half the memory, but also runs
+at half the speed. This is useful under extreme low memory
+circumstances when the file was originally compressed at a high
+@option{--bzip2-compress-level}.
+
+
+@item --mangle-dos-filenames
+@itemx --no-mangle-dos-filenames
+@opindex mangle-dos-filenames
+@opindex no-mangle-dos-filenames
+Older version of Windows cannot handle filenames with more than one
+dot. @option{--mangle-dos-filenames} causes GnuPG to replace (rather
+than add to) the extension of an output filename to avoid this
+problem. This option is off by default and has no effect on non-Windows
+platforms.
+
+@item --ask-cert-level
+@itemx --no-ask-cert-level
+When making a key signature, prompt for a certification level. If this
+option is not specified, the certification level used is set via
+@option{--default-cert-level}. See @option{--default-cert-level} for
+information on the specific levels and how they are
+used. @option{--no-ask-cert-level} disables this option. This option
+defaults to no.
+
+@item --default-cert-level @code{n}
+The default to use for the check level when signing a key.
+
+0 means you make no particular claim as to how carefully you verified
+the key.
+
+1 means you believe the key is owned by the person who claims to own
+it but you could not, or did not verify the key at all. This is
+useful for a "persona" verification, where you sign the key of a
+pseudonymous user.
+
+2 means you did casual verification of the key. For example, this
+could mean that you verified that the key fingerprint and checked the
+user ID on the key against a photo ID.
+
+3 means you did extensive verification of the key. For example, this
+could mean that you verified the key fingerprint with the owner of the
+key in person, and that you checked, by means of a hard to forge
+document with a photo ID (such as a passport) that the name of the key
+owner matches the name in the user ID on the key, and finally that you
+verified (by exchange of email) that the email address on the key
+belongs to the key owner.
+
+Note that the examples given above for levels 2 and 3 are just that:
+examples. In the end, it is up to you to decide just what "casual"
+and "extensive" mean to you.
+
+This option defaults to 0 (no particular claim).
+
+@item --min-cert-level
+When building the trust database, treat any signatures with a
+certification level below this as invalid. Defaults to 2, which
+disregards level 1 signatures. Note that level 0 "no particular
+claim" signatures are always accepted.
+
+@item --trusted-key @code{long key ID}
+Assume that the specified key (which must be given
+as a full 8 byte key ID) is as trustworthy as one of
+your own secret keys. This option is useful if you
+don't want to keep your secret keys (or one of them)
+online but still want to be able to check the validity of a given
+recipient's or signator's key.
+
+@item --trust-model @code{pgp|classic|direct|always|auto}
+Set what trust model GnuPG should follow. The models are:
+
+@table @asis
+
+@item pgp
+This is the Web of Trust combined with trust signatures as used in PGP
+5.x and later. This is the default trust model when creating a new
+trust database.
+
+@item classic
+This is the standard Web of Trust as used in PGP 2.x and earlier.
+
+@item direct
+Key validity is set directly by the user and not calculated via the
+Web of Trust.
+
+@item always
+Skip key validation and assume that used keys are always fully
+trusted. You generally won't use this unless you are using some
+external validation scheme. This option also suppresses the
+"[uncertain]" tag printed with signature checks when there is no
+evidence that the user ID is bound to the key.
+
+@item auto
+Select the trust model depending on whatever the internal trust
+database says. This is the default model if such a database already
+exists.
+@end table
+
+@item --auto-key-locate @code{parameters}
+@itemx --no-auto-key-locate
+GnuPG can automatically locate and retrieve keys as needed using this
+option. This happens when encrypting to an email address (in the
+"user@@example.com" form), and there are no user@@example.com keys on
+the local keyring. This option takes any number of the following
+arguments, in the order they are to be tried:
+
+@table @asis
+
+@item cert
+locate a key using DNS CERT, as specified in 2538bis (currently in
+draft): http://www.josefsson.org/rfc2538bis/
+
+@item pka
+locate a key using DNS PKA.
+
+@item ldap
+locate a key using the PGP Universal method of checking
+"ldap://keys.(thedomain)".
+
+@item keyserver
+locate a key using whatever keyserver is defined using the
+@option{--keyserver} option.
+
+@item (keyserver URL)
+In addition, a keyserver URL as used in the @option{--keyserver} option may be
+used here to query that particular keyserver.
+@end table
+
+@item --keyid-format @code{short|0xshort|long|0xlong}
+Select how to display key IDs. "short" is the traditional 8-character
+key ID. "long" is the more accurate (but less convenient)
+16-character key ID. Add an "0x" to either to include an "0x" at the
+beginning of the key ID, as in 0x99242560.
+
+@item --keyserver @code{name}
+Use @code{name} as your keyserver. This is the server that
+@option{--recv-keys}, @option{--send-keys}, and @option{--search-keys}
+will communicate with to receive keys from, send keys to, and search for
+keys on. The format of the @code{name} is a URI:
+`scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
+"hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
+keyservers, or "mailto" for the Graff email keyserver. Note that your
+particular installation of GnuPG may have other keyserver types
+available as well. Keyserver schemes are case-insensitive. After the
+keyserver name, optional keyserver configuration options may be
+provided. These are the same as the global @option{--keyserver-options}
+from below, but apply only to this particular keyserver.
+
+Most keyservers synchronize with each other, so there is generally no
+need to send keys to more than one server. The keyserver
+@code{hkp://subkeys.pgp.net} uses round robin DNS to give a different
+keyserver each time you use it.
+
+@item --keyserver-options @code{name=value1 }
+This is a space or comma delimited string that gives options for the
+keyserver. Options can be prepended with a `no-' to give the opposite
+meaning. Valid import-options or export-options may be used here as well
+to apply to importing (@option{--recv-key}) or exporting
+(@option{--send-key}) a key from a keyserver. While not all options are
+available for all keyserver types, some common options are:
+
+@table @asis
+
+@item include-revoked
+When searching for a key with @option{--search-keys}, include keys that
+are marked on the keyserver as revoked. Note that not all keyservers
+differentiate between revoked and unrevoked keys, and for such
+keyservers this option is meaningless. Note also that most keyservers do
+not have cryptographic verification of key revocations, and so turning
+this option off may result in skipping keys that are incorrectly marked
+as revoked.
+
+@item include-disabled
+When searching for a key with @option{--search-keys}, include keys that
+are marked on the keyserver as disabled. Note that this option is not
+used with HKP keyservers.
+
+@item auto-key-retrieve
+This option enables the automatic retrieving of keys from a keyserver
+when verifying signatures made by keys that are not on the local
+keyring.
+
+Note that this option makes a "web bug" like behavior possible.
+Keyserver operators can see which keys you request, so by sending you
+a message signed by a brand new key (which you naturally will not have
+on your local keyring), the operator can tell both your IP address and
+the time when you verified the signature.
+
+@item honor-keyserver-url
+When using @option{--refresh-keys}, if the key in question has a preferred
+keyserver URL, then use that preferred keyserver to refresh the key
+from. In addition, if auto-key-retrieve is set, and the signature
+being verified has a preferred keyserver URL, then use that preferred
+keyserver to fetch the key from. Defaults to yes.
+
+@item honor-pka-record
+If auto-key-retrieve is set, and the signature being verified has a
+PKA record, then use the PKA information to fetch the key. Defaults
+to yes.
+
+@item include-subkeys
+When receiving a key, include subkeys as potential targets. Note that
+this option is not used with HKP keyservers, as they do not support
+retrieving keys by subkey id.
+
+@item use-temp-files
+On most Unix-like platforms, GnuPG communicates with the keyserver
+helper program via pipes, which is the most efficient method. This
+option forces GnuPG to use temporary files to communicate. On some
+platforms (such as Win32 and RISC OS), this option is always enabled.
+
+@item keep-temp-files
+If using `use-temp-files', do not delete the temp files after using
+them. This option is useful to learn the keyserver communication
+protocol by reading the temporary files.
+
+@item verbose
+Tell the keyserver helper program to be more verbose. This option can
+be repeated multiple times to increase the verbosity level.
+
+@item timeout
+Tell the keyserver helper program how long (in seconds) to try and
+perform a keyserver action before giving up. Note that performing
+multiple actions at the same time uses this timeout value per action.
+For example, when retrieving multiple keys via @option{--recv-keys}, the
+timeout applies separately to each key retrieval, and not to the
+@option{--recv-keys} command as a whole. Defaults to 30 seconds.
+
+@item http-proxy
+For HTTP-like keyserver schemes that (such as HKP and HTTP itself),
+try to access the keyserver over a proxy. If a @code{value} is
+specified, use this as the HTTP proxy. If no @code{value} is
+specified, the value of the environment variable "http_proxy", if any,
+will be used.
+
+@item max-cert-size
+When retrieving a key via DNS CERT, only accept keys up to this size.
+Defaults to 16384 bytes.
+@end table
+
+@item --completes-needed @code{n}
+Number of completely trusted users to introduce a new
+key signer (defaults to 1).
+
+@item --marginals-needed @code{n}
+Number of marginally trusted users to introduce a new
+key signer (defaults to 3)
+
+@item --max-cert-depth @code{n}
+Maximum depth of a certification chain (default is 5).
+
+@item --simple-sk-checksum
+Secret keys are integrity protected by using a SHA-1 checksum. This
+method is part of the upcoming enhanced OpenPGP specification but
+GnuPG already uses it as a countermeasure against certain attacks.
+Old applications don't understand this new format, so this option may
+be used to switch back to the old behaviour. Using this option bears
+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).
+
+@item --no-sig-cache
+Do not cache the verification status of key signatures.
+Caching gives a much better performance in key listings. However, if
+you suspect that your public keyring is not save against write
+modifications, you can use this option to disable the caching. It
+probably does not make sense to disable it because all kind of damage
+can be done if someone else has write access to your public keyring.
+
+@item --no-sig-create-check
+GnuPG normally verifies each signature right after creation to protect
+against bugs and hardware malfunctions which could leak out bits from
+the secret key. This extra verification needs some time (about 115%
+for DSA keys), and so this option can be used to disable it.
+However, due to the fact that the signature creation needs manual
+interaction, this performance penalty does not matter in most settings.
+
+@item --auto-check-trustdb
+@itemx --no-auto-check-trustdb
+If GnuPG feels that its information about the Web of Trust has to be
+updated, it automatically runs the @option{--check-trustdb} command
+internally.  This may be a time consuming
+process. @option{--no-auto-check-trustdb} disables this option.
+
+@item --use-agent
+@itemx --no-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
+Override the value of the environment variable
+@samp{GPG_AGENT_INFO}. This is only used when @option{--use-agent} has
+been given
+
+@item --lock-once
+Lock the databases the first time a lock is requested
+and do not release the lock until the process
+terminates.
+
+@item --lock-multiple
+Release the locks every time a lock is no longer
+needed. Use this to override a previous @option{--lock-once}
+from a config file.
+
+@item --lock-never
+Disable locking entirely. This option should be used only in very
+special environments, where it can be assured that only one process
+is accessing those files. A bootable floppy with a stand-alone
+encryption system will probably use this. Improper usage of this
+option may lead to data and key corruption.
+
+@item --exit-on-status-write-error
+This option will cause write errors on the status FD to immediately
+terminate the process. That should in fact be the default but it never
+worked this way and thus we need an option to enable this, so that the
+change won't break applications which close their end of a status fd
+connected pipe too early. Using this option along with
+@option{--enable-progress-filter} may be used to cleanly cancel long
+running gpg operations.
+
+@item --limit-card-insert-tries @code{n}
+With @code{n} greater than 0 the number of prompts asking to insert a
+smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
+all ask to insert a card if none has been inserted at startup. This
+option is useful in the configuration file in case an application does
+not know about the smartcard support and waits ad infinitum for an
+inserted card.
+
+@item --no-random-seed-file
+GnuPG uses a file to store its internal random pool over invocations.
+This makes random generation faster; however sometimes write operations
+are not desired. This option can be used to achieve that with the cost of
+slower random generation.
+
+@item --no-greeting
+Suppress the initial copyright message.
+
+@item --no-secmem-warning
+Suppress the warning about "using insecure memory".
+
+@item --no-permission-warning
+Suppress the warning about unsafe file and home directory (@option{--homedir})
+permissions. Note that the permission checks that GnuPG performs are
+not intended to be authoritative, but rather they simply warn about
+certain common permission problems. Do not assume that the lack of a
+warning means that your system is secure.
+
+Note that the warning for unsafe @option{--homedir} permissions cannot be
+suppressed in the gpg.conf file, as this would allow an attacker to
+place an unsafe gpg.conf file in place, and use this file to suppress
+warnings about itself. The @option{--homedir} permissions warning may only be
+suppressed on the command line.
+
+@item --no-mdc-warning
+Suppress the warning about missing MDC integrity protection.
+
+@item --require-secmem
+@itemx --no-require-secmem
+Refuse to run if GnuPG cannot get secure memory. Defaults to no
+(i.e. run, but give a warning).
+
+
+@item --require-cross-certification
+@itemx --no-require-cross-certification
+When verifying a signature made from a subkey, ensure that the cross
+certification "back signature" on the subkey is present and valid.  This
+protects against a subtle attack against subkeys that can sign.
+Defaults to @option{--require-cross-certification} for
+@command{@gpgname}.
+
+@item --expert
+@itemx --no-expert
+Allow the user to do certain nonsensical or "silly" things like
+signing an expired or revoked key, or certain potentially incompatible
+things like generating unusual key types. This also disables certain
+warning messages about potentially incompatible actions. As the name
+implies, this option is for experts only. If you don't fully
+understand the implications of what it allows you to do, leave this
+off. @option{--no-expert} disables this option.
+
+
+
+
+@end table
+
+
+@c *******************************************
+@c ********  KEY RELATED OPTIONS  ************
+@c *******************************************
+@node GPG Key related Options
+@subsection Key related options
+
+@table @gnupgtabopt
+
+@item --recipient @var{name}
+@itemx -r
+@opindex recipient
+Encrypt for user id @var{name}. If this option or
+@option{--hidden-recipient} is not specified, GnuPG asks for the user-id
+unless @option{--default-recipient} is given.
+
+@item --hidden-recipient @var{name}
+@itemx -R
+@opindex hidden-recipient
+Encrypt for user ID @var{name}, but hide the key ID of this user's
+key. This option helps to hide the receiver of the message and is a
+limited countermeasure against traffic analysis. If this option or
+@option{--recipient} is not specified, GnuPG asks for the user ID unless
+@option{--default-recipient} is given.
+
+@item --encrypt-to @code{name}
+Same as @option{--recipient} but this one is intended for use in the
+options file and may be used with your own user-id as an
+"encrypt-to-self". These keys are only used when there are other
+recipients given either by use of @option{--recipient} or by the asked
+user id.  No trust checking is performed for these user ids and even
+disabled keys can be used.
+
+@item --hidden-encrypt-to @code{name}
+Same as @option{--hidden-recipient} but this one is intended for use in the
+options file and may be used with your own user-id as a hidden
+"encrypt-to-self". These keys are only used when there are other
+recipients given either by use of @option{--recipient} or by the asked user id.
+No trust checking is performed for these user ids and even disabled
+keys can be used.
+
+@item --no-encrypt-to
+Disable the use of all @option{--encrypt-to} and
+@option{--hidden-encrypt-to} keys.
+
+@item --group @code{name=value1 }
+Sets up a named group, which is similar to aliases in email programs.
+Any time the group name is a recipient (@option{-r} or
+@option{--recipient}), it will be expanded to the values
+specified. Multiple groups with the same name are automatically merged
+into a single group.
+
+The values are @code{key IDs} or fingerprints, but any key description
+is accepted. Note that a value with spaces in it will be treated as
+two different values. Note also there is only one level of expansion
+--- you cannot make an group that points to another group. When used
+from the command line, it may be necessary to quote the argument to
+this option to prevent the shell from treating it as multiple
+arguments.
+
+@item --ungroup @code{name}
+Remove a given entry from the @option{--group} list.
+
+@item --no-groups
+Remove all entries from the @option{--group} list.
+
+@item --local-user @var{name}
+@itemx -u
+@opindex local-user
+Use @var{name} as the key to sign with. Note that this option overrides
+@option{--default-key}.
+
+@item --try-all-secrets
+Don't look at the key ID as stored in the message but try all secret
+keys in turn to find the right decryption key. This option forces the
+behaviour as used by anonymous recipients (created by using
+@option{--throw-keyids}) and might come handy in case where an encrypted
+message contains a bogus key ID.
+
+
+
+
+
+@end table
+
+@c *******************************************
+@c ********  INPUT AND OUTPUT  ***************
+@c *******************************************
+@node GPG Input and Output
+@subsection Input and Output
+
+@table @gnupgtabopt
+
+@item --armor
+@itemx -a
+@opindex armor
+Create ASCII armored output.  The default is to create the binary
+OpenPGP format.
+
+@item --no-armor
+Assume the input data is not in ASCII armored format.
+
+@item --output @var{file}
+@itemx -o @var{file}
+@opindex output
+Write output to @var{file}.
+
+@item --max-output @code{n}
+@opindex max-output
+This option sets a limit on the number of bytes that will be generated
+when processing a file. Since OpenPGP supports various levels of
+compression, it is possible that the plaintext of a given message may be
+significantly larger than the original OpenPGP message. While GnuPG
+works properly with such messages, there is often a desire to set a
+maximum file size that will be generated before processing is forced to
+stop by the OS limits. Defaults to 0, which means "no limit".
+
+@item --import-options @code{parameters}
+This is a space or comma delimited string that gives options for
+importing keys. Options can be prepended with a `no-' to give the
+opposite meaning. The options are:
+
+@table @asis
+
+@item import-local-sigs
+Allow importing key signatures marked as "local". This is not
+generally useful unless a shared keyring scheme is being used.
+Defaults to no.
+
+@item repair-pks-subkey-bug
+During import, attempt to repair the damage caused by the PKS keyserver
+bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
+that this cannot completely repair the damaged key as some crucial data
+is removed by the keyserver, but it does at least give you back one
+subkey. Defaults to no for regular @option{--import} and to yes for
+keyserver @option{--recv-keys}.
+
+@item merge-only
+During import, allow key updates to existing keys, but do not allow
+any new keys to be imported. Defaults to no.
+
+@item import-clean
+After import, compact (remove all signatures except the
+self-signature) any user IDs from the new key that are not usable.
+Then, remove any signatures from the new key that are not usable.
+This includes signatures that were issued by keys that are not present
+on the keyring. This option is the same as running the @option{--edit-key}
+command "clean" after import. Defaults to no.
+
+@item import-minimal
+Import the smallest key possible. This removes all signatures except
+the most recent self-signature on each user ID. This option is the
+same as running the @option{--edit-key} command "minimize" after import.
+Defaults to no.
+@end table
+
+@item --export-options @code{parameters}
+This is a space or comma delimited string that gives options for
+exporting keys. Options can be prepended with a `no-' to give the
+opposite meaning. The options are:
+
+@table @asis
+
+@item export-local-sigs
+Allow exporting key signatures marked as "local". This is not
+generally useful unless a shared keyring scheme is being used.
+Defaults to no.
+
+@item export-attributes
+Include attribute user IDs (photo IDs) while exporting. This is
+useful to export keys if they are going to be used by an OpenPGP
+program that does not accept attribute user IDs. Defaults to yes.
+
+@item export-sensitive-revkeys
+Include designated revoker information that was marked as
+"sensitive". Defaults to no.
+
+@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.
+
+@item export-clean
+Compact (remove all signatures from) user IDs on the key being
+exported if the user IDs are not usable. Also, do not export any
+signatures that are not usable. This includes signatures that were
+issued by keys that are not present on the keyring. This option is
+the same as running the @option{--edit-key} command "clean" before export
+except that the local copy of the key is not modified. Defaults to
+no.
+
+@item export-minimal
+Export the smallest key possible. This removes all signatures except the
+most recent self-signature on each user ID. This option is the same as
+running the @option{--edit-key} command "minimize" before export except
+that the local copy of the key is not modified. Defaults to no.
+@end table
+
+@item --with-colons
+@opindex with-colons
+Print key listings delimited by colons. Note that the output will be
+encoded in UTF-8 regardless of any @option{--display-charset} setting. This
+format is useful when GnuPG is called from scripts and other programs
+as it is easily machine parsed. The details of this format are
+documented in the file @file{doc/DETAILS}, which is included in the GnuPG
+source distribution.
+
+@item --fixed-list-mode
+@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.
+
+@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.
+
+
+@end table
+
+@c *******************************************
+@c ********  OPENPGP OPTIONS  ****************
+@c *******************************************
+@node OpenPGP Options
+@subsection OpenPGP protocol specific options.
+
+@table @gnupgtabopt
+
+@item -t, --textmode
+@itemx --no-textmode
+Treat input files as text and store them in the OpenPGP canonical text
+form with standard "CRLF" line endings. This also sets the necessary
+flags to inform the recipient that the encrypted or signed data is text
+and may need its line endings converted back to whatever the local
+system uses. This option is useful when communicating between two
+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
+OpenPGP states that an implementation should generate v4 signatures
+but PGP versions 5 through 7 only recognize v4 signatures on key
+material. This option forces v3 signatures for signatures on data.
+Note that this option overrides @option{--ask-sig-expire}, as v3 signatures
+cannot have expiration dates. @option{--no-force-v3-sigs} disables this
+option.
+
+@item --force-v4-certs
+@itemx --no-force-v4-certs
+Always use v4 key signatures even on v3 keys. This option also
+changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
+@option{--no-force-v4-certs} disables this option.
+
+@item --force-mdc
+Force the use of encryption with a modification detection code. This
+is always used with the newer ciphers (those with a blocksize greater
+than 64 bits), or if all of the recipient keys indicate MDC support in
+their feature flags.
+
+@item --disable-mdc
+Disable the use of the modification detection code. Note that by
+using this option, the encrypted message becomes vulnerable to a
+message modification attack.
+
+@item --personal-cipher-preferences @code{string}
+Set the list of personal cipher preferences to @code{string}, this list
+should be a string similar to the one printed by the command "pref" in
+the edit menu. This allows the user to factor in their own preferred
+algorithms when algorithms are chosen via recipient key preferences.
+The most highly ranked cipher in this list is also used for the
+@option{--symmetric} encryption command.
+
+@item --personal-digest-preferences @code{string}
+Set the list of personal digest preferences to @code{string}, this list
+should be a string similar to the one printed by the command "pref" in
+the edit menu. 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 (e.g. @option{--clearsign} or
+@option{--sign}). The default value is SHA-1.
+
+@item --personal-compress-preferences @code{string}
+Set the list of personal compression preferences to @code{string}, this
+list should be a string similar to the one printed by the command
+"pref" in the edit menu. This allows the user to factor in their own
+preferred algorithms when algorithms are chosen via recipient key
+preferences. The most highly ranked 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}
+Use @code{name} as the cipher algorithm used to protect secret keys.
+The default cipher is CAST5. This cipher is also used for
+conventional encryption if @option{--personal-cipher-preferences} and
+@option{--cipher-algo} is not given.
+
+@item --s2k-digest-algo @code{name}
+Use @code{name} as the digest algorithm used to mangle the passphrases.
+The default algorithm is SHA-1.
+
+@item --s2k-mode @code{n}
+Selects how passphrases are mangled. If @code{n} is 0 a plain
+passphrase (which is not recommended) will be used, a 1 adds a salt to
+the passphrase and a 3 (the default) iterates the whole process a
+number of times (see --s2k-count).  Unless @option{--rfc1991} is used,
+this mode is also used for conventional encryption.
+
+@item --s2k-count @code{n}
+Specify how many times the passphrase mangling is repeated.  This
+value may range between 1024 and 65011712 inclusive, and the default
+is 65536.  Note that not all values in the 1024-65011712 range are
+legal and if an illegal value is selected, GnuPG will round up to the
+nearest legal value.  This option is only meaningful if
+@option{--s2k-mode} is 3.
+
+
+@end table
+
+@c ***************************
+@c ******* Compliance ********
+@c ***************************
+@subsection Compliance options
+
+These options control what GnuPG is compliant to. Only one of these
+options may be active at a time. Note that the default setting of
+this is nearly always the correct one. See the INTEROPERABILITY WITH
+OTHER OPENPGP PROGRAMS section below before using one of these
+options.
+
+@table @gnupgtabopt
+
+@item --gnupg
+@opindex gnupg
+Use standard GnuPG behavior. This is essentially OpenPGP behavior
+(see @option{--openpgp}), but with some additional workarounds for common
+compatibility problems in different versions of PGP. This is the
+default option, so it is not generally needed, but it may be useful to
+override a different compliance option in the gpg.conf file.
+
+@item --openpgp
+@opindex openpgp
+Reset all packet, cipher and digest options to strict OpenPGP
+behavior. Use this option to reset all previous options like
+@option{--rfc1991}, @option{--force-v3-sigs}, @option{--s2k-*},
+@option{--cipher-algo}, @option{--digest-algo} and
+@option{--compress-algo} to OpenPGP compliant values. All PGP
+workarounds are disabled.
+
+@item --rfc2440
+@opindex rfc2440
+Reset all packet, cipher and digest options to strict RFC-2440
+behavior. Note that this is currently the same thing as @option{--openpgp}.
+
+@item --rfc1991
+@opindex rfc1991
+Try to be more RFC-1991 (PGP 2.x) compliant.
+
+@item --pgp2
+@opindex pgp2
+Set up all options to be as PGP 2.x compliant as possible, and warn if
+an action is taken (e.g. encrypting to a non-RSA key) that will create
+a message that PGP 2.x will not be able to handle. Note that `PGP
+2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x
+available, but the MIT release is a good common baseline.
+
+This option implies @option{--rfc1991 --disable-mdc --no-force-v4-certs
+--no-sk-comment --escape-from-lines --force-v3-sigs --no-ask-sig-expire
+--no-ask-cert-expire --cipher-algo IDEA --digest-algo MD5
+--compress-algo 1}. It also disables @option{--textmode} when
+encrypting.
+
+@item --pgp6
+@opindex pgp6
+Set up all options to be as PGP 6 compliant as possible. This
+restricts you to the ciphers IDEA (if the IDEA plugin is installed),
+3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
+compression algorithms none and ZIP. This also disables
+--throw-keyids, and making signatures with signing subkeys as PGP 6
+does not understand signatures made by signing subkeys.
+
+This option implies @option{--disable-mdc --no-sk-comment
+--escape-from-lines --force-v3-sigs --no-ask-sig-expire}.
+
+@item --pgp7
+@opindex pgp7
+Set up all options to be as PGP 7 compliant as possible. This is
+identical to @option{--pgp6} except that MDCs are not disabled, and the
+list of allowable ciphers is expanded to add AES128, AES192, AES256, and
+TWOFISH.
+
+@item --pgp8
+@opindex pgp8
+Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot
+closer to the OpenPGP standard than previous versions of PGP, so all
+this does is disable @option{--throw-keyids} and set
+@option{--escape-from-lines}.  All algorithms are allowed except for the
+SHA224, SHA384, and SHA512 digests.
+
+@end table
+
+
+@c *******************************************
+@c ********  ESOTERIC OPTIONS  ***************
+@c *******************************************
+@node GPG Esoteric Options
+@subsection Doing things one usually don't want to do.
+
+@table @gnupgtabopt
+
+@item -n
+@itemx --dry-run
+@opindex dry-run
+Don't make any changes (this is not completely implemented).
+
+@item --list-only
+Changes the behaviour of some commands. This is like @option{--dry-run} but
+different in some cases. The semantic of this command may be extended in
+the future. Currently it only skips the actual decryption pass and
+therefore enables a fast listing of the encryption keys.
+
+@item -i
+@itemx --interactive
+@opindex interactive
+Prompt before overwriting any files.
+
+@item --debug @var{flags}
+@opindex debug
+Set debugging flags. All flags are or-ed and @var{flags} may
+be given in C syntax (e.g. 0x0042).
+
+@item --debug-all
+Set all useful debugging flags.
+
+@ifset gpgone
+@item --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 --enable-progress-filter
+Enable certain PROGRESS status outputs. This option allows frontends
+to display a progress indicator while gpg is processing larger files.
+There is a slight performance overhead using it.
+
+@item --status-fd @code{n}
+Write special status strings to the file descriptor @code{n}.
+See the file DETAILS in the documentation for a listing of them.
+
+@item --status-file @code{file}
+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.
+
+@item --logger-file @code{file}
+Same as @option{--logger-fd}, except the logger data is written to file
+@code{file}.
+
+@item --attribute-fd @code{n}
+Write attribute subpackets to the file descriptor @code{n}. This is most
+useful for use with @option{--status-fd}, since the status messages are
+needed to separate out the various subpackets from the stream delivered
+to the file descriptor.
+
+@item --attribute-file @code{file}
+Same as @option{--attribute-fd}, except the attribute data is written to
+file @code{file}.
+
+@item --comment @code{string}
+@itemx --no-comments
+Use @code{string} as a comment string in clear text signatures and ASCII
+armored messages or keys (see @option{--armor}). The default behavior is
+not to use a comment string. @option{--comment} may be repeated multiple
+times to get multiple comment strings. @option{--no-comments} removes
+all comments.  It is a good idea to keep the length of a single comment
+below 60 characters to avoid problems with mail programs wrapping such
+lines.  Note that comment lines, like all other header lines, are not
+protected by the signature.
+
+@item --emit-version
+@itemx --no-emit-version
+Force inclusion of the version string in ASCII armored output.
+@option{--no-emit-version} disables this option.
+
+@item --sig-notation @code{name=value}
+@itemx --cert-notation @code{name=value}
+@itemx -N, --set-notation @code{name=value}
+Put the name value pair into the signature as notation data.
+@code{name} must consist only of printable characters or spaces, and
+must contain a '@@' character in the form keyname@@domain.example.com
+(substituting the appropriate keyname and domain name, of course).  This
+is to help prevent pollution of the IETF reserved notation
+namespace. The @option{--expert} flag overrides the '@@'
+check. @code{value} may be any printable string; it will be encoded in
+UTF8, so you should check that your @option{--display-charset} is set
+correctly. If you prefix @code{name} with an exclamation mark (!), the
+notation data will be flagged as critical
+(rfc2440:5.2.3.15). @option{--sig-notation} sets a notation for data
+signatures. @option{--cert-notation} sets a notation for key signatures
+(certifications). @option{--set-notation} sets both.
+
+There are special codes that may be used in notation names. "%k" will
+be expanded into the key ID of the key being signed, "%K" into the
+long key ID of the key being signed, "%f" into the fingerprint of the
+key being signed, "%s" into the key ID of the key making the
+signature, "%S" into the long key ID of the key making the signature,
+"%g" into the fingerprint of the key making the signature (which might
+be a subkey), "%p" into the fingerprint of the primary key of the key
+making the signature, "%c" into the signature count from the OpenPGP
+smartcard, and "%%" results in a single "%". %k, %K, and %f are only
+meaningful when making a key signature (certification), and %c is only
+meaningful when using the OpenPGP smartcard.
+
+@item --sig-policy-url @code{string}
+@itemx --cert-policy-url @code{string}
+@itemx --set-policy-url @code{string}
+Use @code{string} as a Policy URL for signatures (rfc2440:5.2.3.19).  If
+you prefix it with an exclamation mark (!), the policy URL packet will
+be flagged as critical. @option{--sig-policy-url} sets a policy url for
+data signatures. @option{--cert-policy-url} sets a policy url for key
+signatures (certifications). @option{--set-policy-url} sets both.
+
+The same %-expandos used for notation data are available here as well.
+
+@item --sig-keyserver-url @code{string}
+Use @code{string} as a preferred keyserver URL for data signatures. If
+you prefix it with an exclamation mark, the keyserver URL packet will
+be flagged as critical.
+
+The same %-expandos used for notation data are available here as well.
+
+@item --set-filename @code{string}
+Use @code{string} as the filename which is stored inside messages.
+This overrides the default, which is to use the actual filename of the
+file being encrypted.
+
+@item --for-your-eyes-only
+@itemx --no-for-your-eyes-only
+Set the `for your eyes only' flag in the message. This causes GnuPG
+to refuse to save the file unless the @option{--output} option is given, and
+PGP to use the "secure viewer" with a Tempest-resistant font to
+display the message. This option overrides @option{--set-filename}.
+@option{--no-for-your-eyes-only} disables this option.
+
+@item --use-embedded-filename
+@itemx --no-use-embedded-filename
+Try to create a file with a name as embedded in the data. This can be
+a dangerous option as it allows to overwrite files. Defaults to no.
+
+@item --cipher-algo @code{name}
+Use @code{name} as cipher algorithm. Running the program with the
+command @option{--version} yields a list of supported algorithms. If
+this is not used the cipher algorithm is selected from the preferences
+stored with the key. In general, you do not want to use this option as
+it allows you to violate the OpenPGP standard.
+@option{--personal-cipher-preferences} is the safe way to accomplish the
+same thing.
+
+@item --digest-algo @code{name}
+Use @code{name} as the message digest algorithm. Running the program
+with the command @option{--version} yields a list of supported algorithms. In
+general, you do not want to use this option as it allows you to
+violate the OpenPGP standard. @option{--personal-digest-preferences} is the
+safe way to accomplish the same thing.
+
+@item --compress-algo @code{name}
+Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
+compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
+"bzip2" is a more modern compression scheme that can compress some
+things better than zip or zlib, but at the cost of more memory used
+during compression and decompression. "uncompressed" or "none"
+disables compression. If this option is not used, the default
+behavior is to examine the recipient key preferences to see which
+algorithms the recipient supports. If all else fails, ZIP is used for
+maximum compatibility.
+
+ZLIB may give better compression results than ZIP, as the compression
+window size is not limited to 8k. BZIP2 may give even better
+compression results than that, but will use a significantly larger
+amount of memory while compressing and decompressing. This may be
+significant in low memory situations. Note, however, that PGP (all
+versions) only supports ZIP compression. Using any algorithm other
+than ZIP or "none" will make the message unreadable with PGP. In
+general, you do not want to use this option as it allows you to
+violate the OpenPGP standard. @option{--personal-compress-preferences} is the
+safe way to accomplish the same thing.
+
+@item --cert-digest-algo @code{name}
+Use @code{name} as the message digest algorithm used when signing a
+key. Running the program with the command @option{--version} yields a
+list of supported algorithms. Be aware that if you choose an algorithm
+that GnuPG supports but other OpenPGP implementations do not, then some
+users will not be able to use the key signatures you make, or quite
+possibly your entire key.
+
+@item --disable-cipher-algo @code{name}
+Never allow the use of @code{name} as cipher algorithm.
+The given name will not be checked so that a later loaded algorithm
+will still get disabled.
+
+@item --disable-pubkey-algo @code{name}
+Never allow the use of @code{name} as public key algorithm.
+The given name will not be checked so that a later loaded algorithm
+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.
+
+@item --not-dash-escaped
+This option changes the behavior of cleartext signatures
+so that they can be used for patch files. You should not
+send such an armored file via email because all spaces
+and line endings are hashed too. You can not use this
+option for data which has 5 dashes at the beginning of a
+line, patch files don't have this. A special armor header
+line tells GnuPG about this cleartext signature option.
+
+@item --escape-from-lines
+@itemx --no-escape-from-lines
+Because some mailers change lines starting with "From " to ">From " it
+is good to handle such lines in a special way when creating cleartext
+signatures to prevent the mail system from breaking the signature. Note
+that all other PGP versions do it this way too.  Enabled by
+default. @option{--no-escape-from-lines} disables this option.
+
+@item --passphrase-repeat @code{n}
+Specify how many times @command{@gpgname} will request a new
+passphrase be repeated.  This is useful for helping memorize a
+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
+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}
+Read the passphrase from file @code{file}. Only the first line will
+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}
+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
+
+@item --command-fd @code{n}
+This is a replacement for the deprecated shared-memory IPC mode.
+If this option is enabled, user input on questions is not expected
+from the TTY but from the given file descriptor. It should be used
+together with @option{--status-fd}. See the file doc/DETAILS in the source
+distribution for details on how to use it.
+
+@item --command-file @code{file}
+Same as @option{--command-fd}, except the commands are read out of file
+@code{file}
+
+@item --allow-non-selfsigned-uid
+@itemx --no-allow-non-selfsigned-uid
+Allow the import and use of keys with user IDs which are not
+self-signed. This is not recommended, as a non self-signed user ID is
+trivial to forge. @option{--no-allow-non-selfsigned-uid} disables.
+
+@item --allow-freeform-uid
+Disable all checks on the form of the user ID while generating a new
+one. This option should only be used in very special environments as
+it does not ensure the de-facto standard format of user IDs.
+
+@item --ignore-time-conflict
+GnuPG normally checks that the timestamps associated with keys and
+signatures have plausible values. However, sometimes a signature
+seems to be older than the key due to clock problems. This option
+makes these checks just a warning. See also @option{--ignore-valid-from} for
+timestamp issues on subkeys.
+
+@item --ignore-valid-from
+GnuPG normally does not select and use subkeys created in the future.
+This option allows the use of such keys and thus exhibits the
+pre-1.0.7 behaviour. You should not use this option unless you there
+is some clock problem. See also @option{--ignore-time-conflict} for timestamp
+issues with signatures.
+
+@item --ignore-crc-error
+The ASCII armor used by OpenPGP is protected by a CRC checksum against
+transmission errors. Occasionally the CRC gets mangled somewhere on
+the transmission channel but the actual content (which is protected by
+the OpenPGP protocol anyway) is still okay. This option allows GnuPG
+to ignore CRC errors.
+
+@item --ignore-mdc-error
+This option changes a MDC integrity protection failure into a warning.
+This can be useful if a message is partially corrupt, but it is
+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.
+
+@item --no-default-keyring
+Do not add the default keyrings to the list of keyrings. Note that
+GnuPG will not operate without any keyrings, so if you use this option
+and do not provide alternate keyrings via @option{--keyring} or
+@option{--secret-keyring}, then GnuPG will still use the default public or
+secret keyrings.
+
+@item --skip-verify
+Skip the signature verification step. This may be
+used to make the decryption faster if the signature
+verification is not needed.
+
+@item --with-key-data
+Print key listings delimited by colons (like @option{--with-colons}) and
+print the public key data.
+
+@item --fast-list-mode
+Changes the output of the list commands to work faster; this is achieved
+by leaving some parts empty. Some applications don't need the user ID
+and the trust information given in the listings. By using this options
+they can get a faster listing. The exact behaviour of this option may
+change in future versions.  If you are missing some information, don't
+use this option.
+
+@item --no-literal
+This is not for normal use. Use the source to see for what it might be useful.
+
+@item --set-filesize
+This is not for normal use. Use the source to see for what it might be useful.
+
+@item --show-session-key
+Display the session key used for one message. See
+@option{--override-session-key} for the counterpart of this option.
+
+We think that Key Escrow is a Bad Thing; however the user should have
+the freedom to decide whether to go to prison or to reveal the content
+of one specific message without compromising all messages ever
+encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY
+FORCED TO DO SO.
+
+@item --override-session-key @code{string}
+Don't use the public key but the session key @code{string}. The format
+of this string is the same as the one printed by
+@option{--show-session-key}. This option is normally not used but comes
+handy in case someone forces you to reveal the content of an encrypted
+message; using this option you can do this without handing out the
+secret key.
+
+@item --ask-sig-expire
+@itemx --no-ask-sig-expire
+When making a data signature, prompt for an expiration time. If this
+option is not specified, the expiration time set via
+@option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
+disables this option. Note that by default, @option{--force-v3-sigs} is
+set which also disables this option. If you want signature expiration,
+you must set @option{--no-force-v3-sigs} as well as turning
+@option{--ask-sig-expire} on.
+
+@item --default-sig-expire
+The default expiration time to use for signature expiration. Valid
+values are "0" for no expiration, a number followed by the letter d
+(for days), w (for weeks), m (for months), or y (for years) (for
+example "2m" for two months, or "5y" for five years), or an absolute
+date in the form YYYY-MM-DD. Defaults to "0".
+
+@item --ask-cert-expire
+@itemx --no-ask-cert-expire
+When making a key signature, prompt for an expiration time. If this
+option is not specified, the expiration time set via
+@option{--default-cert-expire} is used. @option{--no-ask-cert-expire}
+disables this option.
+
+@item --default-cert-expire
+The default expiration time to use for key signature expiration.
+Valid values are "0" for no expiration, a number followed by the
+letter d (for days), w (for weeks), m (for months), or y (for years)
+(for example "2m" for two months, or "5y" for five years), or an
+absolute date in the form YYYY-MM-DD. Defaults to "0".
+
+@item --allow-secret-key-import
+This is an obsolete option and is not used anywhere.
+
+@item --allow-multisig-verification
+Allow verification of concatenated signed messages. This will run a
+signature verification for each data+signature block. There are some
+security issues with this option and thus it is off by default. Note
+that versions of GPG prior to version 1.4.3 implicitly allowed this.
+
+@item --enable-special-filenames
+This options enables a mode in which filenames of the form
+@file{-&n}, where n is a non-negative decimal number,
+refer to the file descriptor n and not to a file with that name.
+
+@item --no-expensive-trust-checks
+Experimental use only.
+
+@item --preserve-permissions
+Don't change the permissions of a secret keyring back to user
+read/write only. Use this option only if you really know what you are doing.
+
+@item --default-preference-list @code{string}
+@opindex default-preference-list
+Set the list of default preferences to @code{string}. This preference
+list is used for new keys and becomes the default for "setpref" in the
+edit menu.
+
+@item --default-keyserver-url @code{name}
+@opindex default-keyserver-url
+Set the default keyserver URL to @code{name}. This keyserver will be
+used as the keyserver URL when writing a new self-signature on a key,
+which includes key generation and changing preferences.
+
+@item --list-config
+@opindex list-config
+Display various internal configuration parameters of GnuPG. This option
+is intended for external programs that call GnuPG to perform tasks, and
+is thus not generally useful. See the file @file{doc/DETAILS} in the
+source distribution for the details of which configuration items may be
+listed. @option{--list-config} is only usable with
+@option{--with-colons} set.
+
+@item --gpgconf-list
+@opindex gpgconf-list
+This command is simliar to @option{--list-config} but in general only
+internally used by the @command{gpgconf} tool.
+
+@item --gpgconf-test
+@opindex gpgconf-test
+This is more or less dummy action.  However it parses the configuration
+file and returns with failure if the configuraion file would prevent
+@command{gpg} from startup.  Thus it may be used to run a syntax check
+on the configuration file.
+
+@end table
+
+@c *******************************
+@c ******* Deprecated ************
+@c *******************************
+@subsection Deprecated options
+
+@table @gnupgtabopt
+
+@ifset gpgone
+@item --load-extension @code{name}
+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
+Causes @option{--list-keys}, @option{--list-sigs},
+@option{--list-public-keys}, @option{--list-secret-keys}, and verifying
+a signature to also display the photo ID attached to the key, if
+any. See also @option{--photo-viewer}. These options are deprecated. Use
+@option{--list-options [no-]show-photos} and/or @option{--verify-options
+[no-]show-photos} instead.
+
+@item --show-keyring
+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.
+
+@item --ctapi-driver @code{file}
+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.
+
+@item --always-trust
+Identical to @option{--trust-model always}. This option is deprecated.
+
+@item --show-notation
+@itemx --no-show-notation
+Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings
+as well as when verifying a signature with a notation in it. These
+options are deprecated. Use @option{--list-options [no-]show-notation}
+and/or @option{--verify-options [no-]show-notation} instead.
+
+@item --show-policy-url
+@itemx --no-show-policy-url
+Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
+listings as well as when verifying a signature with a policy URL in
+it. These options are deprecated. Use @option{--list-options
+[no-]show-policy-url} and/or @option{--verify-options
+[no-]show-policy-url} instead.
+
+
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************   FILES    ****************
+@c ***************            ****************
+@c *******************************************
+@mansect files
+@node GPG Configuration
+@section Configuration files
+
+There are a few configuration files to control certain aspects of
+@command{@gpgname}'s operation. Unless noted, they are expected in the
+current home directory (@pxref{option --homedir}).
+
+@table @file
+
+@item gpg.conf
+@cindex gpgsm.conf
+This is the standard configuration file read by @command{@gpgname} on
+startup.  It may contain any valid long option; the leading two dashes
+may not be entered and the option may not be abbreviated.  This default
+name may be changed on the command line (@pxref{option
+  --options}).
+
+@end table
+
+@c man:.RE
+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 maintaines a few other
+files; They all live in in the current home directory (@pxref{option
+--homedir}).  Only the @command{@gpgname} may modify these files.
+
+
+@table @file
+@item ~/.gnupg/secring.gpg
+The secret keyring.
+
+@item ~/.gnupg/secring.gpg.lock
+and the lock file
+
+@item ~/.gnupg/pubring.gpg
+The public keyring
+
+@item ~/.gnupg/pubring.gpg.lock
+and the lock file
+
+@item ~/.gnupg/trustdb.gpg
+The trust database
+
+@item ~/.gnupg/trustdb.gpg.lock
+and the lock file
+
+@item ~/.gnupg/random_seed
+used to preserve the internal random pool
+
+@item /usr[/local]/share/gnupg/options.skel
+Skeleton options file
+
+@item /usr[/local]/lib/gnupg/
+Default location for extensions
+
+@end table
+
+@c man:.RE
+Operation is further controlled by a few environment variables:
+
+@table @asis
+
+@item HOME
+Used to locate the default home directory.
+
+@item GNUPGHOME
+If set directory used instead of "~/.gnupg".
+
+@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
+as described in its documentation, this variable is set to the correct
+value. The option @option{--gpg-agent-info} can be used to override it.
+
+@item COLUMNS
+@itemx LINES
+Used to size some displays to the full size of the screen.
+
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  EXAMPLES  ****************
+@c ***************            ****************
+@c *******************************************
+@mansect examples
+@node GPG Examples
+@section Examples
+
+@table @asis
+
+@item gpg -se -r @code{Bob} @code{file}
+sign and encrypt for user Bob
+
+@item gpg --clearsign @code{file}
+make a clear text signature
+
+@item gpg -sb @code{file}
+make a detached signature
+
+@item gpg --list-keys @code{user_ID}
+show keys
+
+@item gpg --fingerprint @code{user_ID}
+show fingerprint
+
+@item gpg --verify @code{pgpfile}
+@itemx gpg --verify @code{sigfile}
+Verify the signature of the file but do not output the data. The
+second form is used for detached signatures, where @code{sigfile}
+is the detached signature (either ASCII armored or binary) and
+are the signed data; if this is not given, the name of
+the file holding the signed data is constructed by cutting off the
+extension (".asc" or ".sig") of @code{sigfile} or by asking the
+user for the filename.
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  USER ID   ****************
+@c ***************            ****************
+@c *******************************************
+@mansect how to specify a user id
+@ifset isman
+@include specify-user-id.texi
+@end ifset
+
+@mansect return vaue
+@chapheading RETURN VALUE
+
+The program returns 0 if everything was fine, 1 if at least
+a signature was bad, and other error codes for fatal errors.
+
+@mansect warnings
+@chapheading WARNINGS
+
+Use a *good* password for your user account and a *good* passphrase
+to protect your secret key. This passphrase is the weakest part of the
+whole system. Programs to do dictionary attacks on your secret keyring
+are very easy to write and so you should protect your "~/.gnupg/"
+directory very well.
+
+Keep in mind that, if this program is used over a network (telnet), it
+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.
+
+@mansect interoperability
+@chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
+
+GnuPG tries to be a very flexible implementation of the OpenPGP
+standard. In particular, GnuPG implements many of the optional parts
+of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
+compression algorithms. It is important to be aware that not all
+OpenPGP programs implement these optional algorithms and that by
+forcing their use via the @option{--cipher-algo}, @option{--digest-algo},
+@option{--cert-digest-algo}, or @option{--compress-algo} options in GnuPG, it is
+possible to create a perfectly valid OpenPGP message, but one that
+cannot be read by the intended recipient.
+
+There are dozens of variations of OpenPGP programs available, and each
+supports a slightly different subset of these optional algorithms.
+For example, until recently, no (unhacked) version of PGP supported
+the BLOWFISH cipher algorithm. A message using BLOWFISH simply could
+not be read by a PGP user. By default, GnuPG uses the standard
+OpenPGP preferences system that will always do the right thing and
+create messages that are usable by all recipients, regardless of which
+OpenPGP program they use. Only override this safe default if you
+really know what you are doing.
+
+If you absolutely must override the safe default, or if the preferences
+on a given key are invalid for some reason, you are far better off using
+the @option{--pgp6}, @option{--pgp7}, or @option{--pgp8} options. These
+options are safe as they do not force any particular algorithms in
+violation of OpenPGP, but rather reduce the available algorithms to a
+"PGP-safe" list.
+
+@mansect bugs
+@chapheading BUGS
+
+On many systems this program should be installed as setuid(root). This
+is necessary to lock memory pages. Locking memory pages prevents the
+operating system from writing memory pages (which may contain
+passphrases or other sensitive material) to disk. If you get no
+warning message about insecure memory your operating system supports
+locking without being root. The program drops root privileges as soon
+as locked memory is allocated.
+
+@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