Copied gpg.texi over from 1.4.5 and started to restructure it into a proper
authorWerner Koch <wk@gnupg.org>
Wed, 16 Aug 2006 14:54:19 +0000 (14:54 +0000)
committerWerner Koch <wk@gnupg.org>
Wed, 16 Aug 2006 14:54:19 +0000 (14:54 +0000)
documentation file.  Comment tags will eventually allow to build a man page.
The idea is to have more than just a reference manual for the commands and
options while still allowing to build a man page for reference.

doc/gpg.texi
doc/gpgsm.texi

index 3254c94..3459c65 100644 (file)
@@ -1,4 +1,5 @@
-@c Copyright (C) 2004 Free Software Foundation, Inc.
+@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.
 
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
 
 @c man begin DESCRIPTION
 
 
 @c man begin DESCRIPTION
 
-@command{gpg} is the OpenPGP part of GnuPG.  The version included in
-this package is not as matured as the standard versions (1.2.x or
-1.4.x) and thus we strongly suggest to keep on using the one of the
-standard versions.  Both versions may be installed side by side and
-should coexists without problems.  To help for that, the @command{gpg}
-from this package gets installed under the name @command{gpg2}. If you
-really want to use this @command{gpg2} command you should name the
-configuration file @file{gpg.conf-1.9} to keep it separate from the
-one used with the standard @command{gpg}.
-
-Documentation for the old standard @command{gpg} is available in a
+@command{gpg2} is the OpenPGP part of GnuPG. It is a tool to provide
+digitla encryption and signing services using the OpenPGP
+standard. @command{gpg2} features complete key management and all bells
+and whistles you can expect from a decent OpenPGP implementation.
+
+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}.
+
+Documentation for the old standard @command{gpg} is available as man page
 man page and at @inforef{Top,GnuPG 1,gpg}.
 
 man page and at @inforef{Top,GnuPG 1,gpg}.
 
+@c man end
+
+@xref{Option Index}, for an index to @command{GPG}'s commands and options.
+
+@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 *******************************************
+@c man begin COMMANDS
+
+@node GPG Commands
+@section Commands
+
+Commands are not distinguished from options execpt for the fact that
+only one command is allowed.
+
+@code{gpg2} 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 "--".
+
+
+@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, -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 --encrypt (for a
+signed and encrypted message), --symmetric (for a signed and
+symmetrically encrypted message), or --encrypt and --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 --sign (for a signed
+and encrypted message), --symmetric (for a message that may be
+decrypted via a secret key or a passphrase), or --sign and --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
+--cipher-algo option. This option may be combined with --sign (for a
+signed and symmetrically encrypted message), --encrypt (for a message
+that may be decrypted via a secret key or a passphrase), or --sign and
+--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
+--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. --multifile may currently be used along with --verify, --encrypt,
+and --decrypt. Note that `--multifile --verify' may not be used with
+detached signatures.
+
+@item --verify-files 
+@opindex verify-files
+Identical to `--multifile --verify'.
+
+@item --encrypt-files 
+@opindex encrypt-files
+Identical to `--multifile --encrypt'.
+
+@item --decrypt-files 
+@opindex decrypt-files
+Identical to `--multifile --decrypt'.
+
+@item --list-keys 
+@itemx -k
+@itemx --list-public-keys 
+@opindex list-keys
+List all keys from the public keyrings, or just the ones given on the
+command line.
+
+Avoid using the output of this command in scripts or other programs as
+it is likely to change as GnuPG changes. See --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
+--export-secret-subkeys).
+
+@item --list-sigs 
+@opindex list-sigs
+Same as --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 --ask-cert-level), "L" for a local or non-exportable
+signature (see --lsign-key), "R" for a nonRevocable signature (see the
+--edit-key command "nrsign"), "P" for a signature that contains a policy
+URL (see --cert-policy-url), "N" for a signature that contains a
+notation (see --cert-notation), "X" for an eXpired signature (see
+--ask-cert-expire), and the numbers 1-9 or "T" for 10 and above to
+indicate trust signature levels (see the --edit-key command "tsign").
+
+@item --check-sigs 
+@opindex check-sigs
+Same as --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 --list-keys but with the
+additional output of a line with the fingerprint. May also be combined
+with --list-sigs or --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
+--card-edit command.
+
+@item --delete-key @code{name}
+@opindex delete-key
+Remove key from the public keyring. In batch mode either --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 --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 --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 "output". Use together with --armor to mail those
+keys.
+
+@item --send-keys 
+@opindex send-keys
+Same as --export but sends the keys to a keyserver.  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 --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
+--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 --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
+--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 --keyserver must be used to give
+the name of the keyserver for all keys that do not have preferred
+keyservers set (see --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 --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 --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 --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 --update-trustdb but it skips keys with a not yet
+defined "ownertrust".
+
+For use with cron jobs, this command can be used together with --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 --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
+ThisWhen 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.
+
+@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 --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
+
+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.
+
+@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
+--default-preference-list), and calling setpref with "none" as the
+argument sets an empty preference list. Use "gpg --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
+--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
+--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
+--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
+
+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:
+
+@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 --edit. 
+
+@item --lsign-key @code{name}
+@opindex lsign-ket
+Signs a public key with your secret key but marks it as
+non-exportable. This is a shortcut version of the subcommand "lsign"
+from --edit.
+
+
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  OPTIONS   ****************
+@c ***************            ****************
+@c *******************************************
+@node GPG Options
+@section Option Summary
+
+@command{GPG} 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
+
+@c man begin OPTIONS
+
+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
+"--".
+
+@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 XXX
+foo
+
+@end table
+
+
+@c *******************************************
+@c ********  KEY RELATED OPTIONS  ************
+@c *******************************************
+@node GPG Key related Options
+@subsection Key related options
+
+@table @gnupgtabopt
+
+@item XXX
+foo
+
+@end table
+
+@c *******************************************
+@c ********  INPUT AND OUTPUT  ***************
+@c *******************************************
+@node GPG Input and Output
+@subsection Input and Output
+
+@table @gnupgtabopt
+
+@item XXX
+foo
+
+@end table
+
+@c *******************************************
+@c ********  OPENPGP OPTIONS  ****************
+@c *******************************************
+@node OpenPGP Options
+@subsection OpenPGP protocol specific options.
+
+@table @gnupgtabopt
+
+@item XXX
+foo
+
+@end table
+
+@c *******************************************
+@c ********  ESOTERIC OPTIONS  ***************
+@c *******************************************
+@node GPG Esoteric Options
+@subsection Doing things one usually don't want to do.
+
+@table @gnupgtabopt
+
+@item XXX
+foo
+
+
+@item --armor
+@itemx -a
+@opindex armor
+Create ASCII armored output.  The default is to create the binary
+OpenPGP 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 --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. --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 --local-user @var{name}
+@itemx -u
+@opindex local-user
+Use @var{name} as the key to sign with. Note that this option overrides
+--default-key.
+
+@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 -u or --local-user overrides this option.
+
+@item --recipient @var{name}
+@itemx -r
+@opindex recipient
+Encrypt for user id @var{name}. If this option or --hidden-recipient is
+not specified, GnuPG asks for the user-id unless --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
+--recipient is not specified, GnuPG asks for the user ID unless
+--default-recipient is given.
+
+@item --default-recipient @var{name}
+@opindex default-recipient
+Use @var{name} as default recipient if 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 --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 --default-key.
+
+@item --no-default-recipient
+@opindex no-default-recipient
+Reset --default-recipient and --default-recipient-self.
+
+@item --encrypt-to @code{name}
+Same as --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 --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 --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 --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 --encrypt-to and --hidden-encrypt-to keys.
+
+@item -v, --verbose
+Give more information during processing. If used
+twice, the input data is listed in detail.
+
+@item -q, --quiet
+Try to be as quiet as possible.
+
+@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). --bzip2-compress-level sets the compression level
+for the BZIP2 compression algorithm (defaulting to 6 as well). This
+is a different option from --compress-level since BZIP2 uses a
+significant amount of memory for each additional compression level.
+-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
+--bzip2-compress-level.
+
+@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). --no-textmode disables this option, and
+is the default.
+
+If -t (but not --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 --sign or --clearsign to select the type of the
+signature.
+
+@item -n, --dry-run
+Don't make any changes (this is not completely implemented).
+
+@item -i, --interactive
+Prompt before overwriting any files.
+
+@item --batch
+@itemx --no-batch
+Use batch mode. Never ask, do not allow interactive commands.
+--no-batch disables this option.
+
+@item --no-tty
+Make sure that the TTY (terminal) is never used for any output.
+This option is needed in some cases because GnuPG sometimes prints
+warnings to the TTY if --batch is used.
+
+@item --yes
+Assume "yes" on most questions.
+
+@item --no
+Assume "no" on most questions.
+
+@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
+--default-cert-level. See --default-cert-level for information on the
+specific levels and how they are used. --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 --always-trust
+Identical to `--trust-model always'. This option is deprecated.
+
+@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 --keyserver
+option.
+
+@item (keyserver URL)
+In addition, a keyserver URL as used in the --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
+--recv-keys, --send-keys, and --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 --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
+"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 (--recv-key) or exporting (--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 --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 --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 --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 --recv-keys, the
+timeout applies separately to each key retrieval, and not to the
+--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 --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 --import and to
+yes for keyserver --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 --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 --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 "--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 --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 --edit-key command "minimize" before export except
+that the local copy of the key is not modified. Defaults to no.
+@end table
+
+@item --list-options @code{parameters}
+This is a space or comma delimited string that gives options used when
+listing keys and signatures (that is, --list-keys, --list-sigs,
+--list-public-keys, --list-secret-keys, and the --edit-key functions).
+Options can be prepended with a `no-' to give the opposite meaning.
+The options are:
+
+@table @asis
+
+@item show-photos
+Causes --list-keys, --list-sigs, --list-public-keys, and
+--list-secret-keys to display any photo IDs attached to the key.
+Defaults to no. See also --photo-viewer.
+
+@item show-policy-urls
+Show policy URLs in the --list-sigs or --check-sigs listings.
+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
+--list-sigs or --check-sigs listings. Defaults to no.
+
+@item show-keyserver-urls
+Show any preferred keyserver URL in the --list-sigs or --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 --list-sigs or
+--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 --with-colons along with --list-sigs or
+--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 --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 --show-photos
+@itemx --no-show-photos
+Causes --list-keys, --list-sigs, --list-public-keys,
+--list-secret-keys, and verifying a signature to also display the
+photo ID attached to the key, if any. See also --photo-viewer. These
+options are deprecated. Use `--list-options [no-]show-photos' and/or
+`--verify-options [no-]show-photos' instead.
+
+@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 --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
+`--list-options [no-]show-keyring' instead.
+
+@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 --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 --keyring along with
+--no-default-keyring.
+
+@item --secret-keyring @code{file}
+Same as --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 --import or keyserver --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 ("~/.gnupg" if --homedir or $GNUPGHOME
+is not used).
+
+@item --homedir @code{directory}
+Set the name of the home directory to @code{directory} If this option is not
+used it defaults to "~/.gnupg". It does not make sense to use this in
+a options file. This also overrides the environment variable
+$GNUPGHOME.
+
+@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 --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 --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 (--no-utf8-strings) is to assume that arguments are encoded in
+the character set as specified by --display-charset. These options
+affect all following arguments. Both options may be used multiple
+times.
+
+@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 --homedir). This option is ignored if used
+in an options file.
+
+@item --no-options
+Shortcut for "--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 
+"~./gnupg" homedir.
+
+@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.
+
+@item --debug @code{flags}
+Set debugging flags. All flags are or-ed and @code{flags} may
+be given in C syntax (e.g. 0x0042).
+
+@item --debug-all
+Set all useful debugging flags.
+
+@item --debug-ccid-driver
+Enable debug output from the included CCID driver for smartcards.
+Note that this option is only available on some system.
+
+@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 --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 --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 --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 --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 --armor). The default behavior is
+not to use a comment string. --comment may be repeated multiple times
+to get multiple comment strings. --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.
+--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 --expert flag overrides the '@@' check. @code{value}
+may be any printable string; it will be encoded in UTF8, so you should
+check that your --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). --sig-notation sets a
+notation for data signatures. --cert-notation sets a notation for key
+signatures (certifications). --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 --show-notation
+@itemx --no-show-notation
+Show signature notations in the --list-sigs or --check-sigs listings
+as well as when verifying a signature with a notation in it. These
+options are deprecated. Use `--list-options [no-]show-notation'
+and/or `--verify-options [no-]show-notation' instead.
+
+@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. --sig-policy-url sets a policy url for
+data signatures. --cert-policy-url sets a policy url for key
+signatures (certifications). --set-policy-url sets both.
+
+The same %-expandos used for notation data are available here as well.
+
+@item --show-policy-url
+@itemx --no-show-policy-url
+Show policy URLs in the --list-sigs or --check-sigs listings as well
+as when verifying a signature with a policy URL in it. These options
+are deprecated. Use `--list-options [no-]show-policy-url' and/or
+`--verify-options [no-]show-policy-url' instead.
+
+@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 --output option is given, and
+PGP to use the "secure viewer" with a Tempest-resistant font to
+display the message. This option overrides --set-filename.
+--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 --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 --cipher-algo @code{name}
+Use @code{name} as cipher algorithm. Running the program with the
+command --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.
+--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 --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. --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. --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 --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 --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 --personal-cipher-preferences and
+--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
+couple of times. Unless --rfc1991 is used, this mode is also used for
+conventional encryption.
+
+@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 --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 --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 --check-trustdb command internally.
+This may be a time consuming process. --no-auto-check-trustdb
+disables this option.
+
+@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.
+--no-throw-keyids disables this option. This option is essentially
+the same as using --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. --no-escape-from-lines disables this option.
+
+@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.
+
+@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.
+
+@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.
+
+@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 --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 --command-fd, except the commands are read out of file
+@code{file}
+
+@item --use-agent
+@itemx --no-use-agent
+Try to use the GnuPG-Agent. Please note that this agent is still under
+development. With this option, GnuPG first tries to connect to the
+agent before it asks for a passphrase. --no-use-agent disables this
+option.
+
+@item --gpg-agent-info
+Override the value of the environment variable
+@samp{GPG_AGENT_INFO}. This is only used when --use-agent has been given
+
+@item 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 @asis
+
+@item --gnupg
+Use standard GnuPG behavior. This is essentially OpenPGP behavior
+(see --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
+Reset all packet, cipher and digest options to strict OpenPGP
+behavior. Use this option to reset all previous options like
+--rfc1991, --force-v3-sigs, --s2k-*, --cipher-algo, --digest-algo and
+--compress-algo to OpenPGP compliant values. All PGP workarounds are
+disabled.
+
+@item --rfc2440
+Reset all packet, cipher and digest options to strict RFC-2440
+behavior. Note that this is currently the same thing as --openpgp.
+
+@item --rfc1991
+Try to be more RFC-1991 (PGP 2.x) compliant.
+
+@item --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 `--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 --textmode
+when encrypting.
+
+@item --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 `--disable-mdc --no-sk-comment --escape-from-lines
+--force-v3-sigs --no-ask-sig-expire'
+
+@item --pgp7
+Set up all options to be as PGP 7 compliant as possible. This is
+identical to --pgp6 except that MDCs are not disabled, and the list of
+allowable ciphers is expanded to add AES128, AES192, AES256, and
+TWOFISH.
+
+@item --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 --throw-keyids and set --escape-from-lines.
+All algorithms are allowed except for the SHA224, SHA384, and SHA512
+digests.
+@end table
+
+@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 --ask-sig-expire, as v3 signatures
+cannot have expiration dates. --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.
+--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 --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. --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 --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 --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 --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 --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
+--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-verbose
+Reset verbose level to 0.
+
+@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 (--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 --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 --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 --no-armor
+Assume the input data is not in ASCII armored format.
+
+@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 --keyring or
+--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-colons
+Print key listings delimited by colons. Note that the output will be
+encoded in UTF-8 regardless of any --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 doc/DETAILS, which is included in the GnuPG
+source distribution.
+
+@item --with-key-data
+Print key listings delimited by colons (like --with-colons) and print the public key data.
+
+@item --with-fingerprint
+Same as the command --fingerprint but changes only the format of the output
+and may be used together with another command.
+
+@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.
+
+@item --fixed-list-mode
+Do not merge primary user ID and primary key in --with-colon listing
+mode and print all timestamps as seconds since 1970-01-01.
+
+@item --list-only
+Changes the behaviour of some commands. This is like --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 --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 --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 --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 --require-cross-certification
+@itemx --no-require-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.
+Currently defaults to --no-require-cross-certification, but will be
+changed to --require-cross-certification in the future.
+
+@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
+--default-sig-expire is used. --no-ask-sig-expire disables this
+option. Note that by default, --force-v3-sigs is set which also
+disables this option. If you want signature expiration, you must set
+--no-force-v3-sigs as well as turning --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
+--default-cert-expire is used. --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 --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. --no-expert disables this option.
+
+@item --allow-secret-key-import
+This is an obsolete option and is not used anywhere.
+
+@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
+--throw-keyids) and might come handy in case where an encrypted
+message contains a bogus key ID.
+
+@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 --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 (-r or --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 --group list.
+
+@item --no-groups
+Remove all entries from the --group list.
+
+@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 --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
+--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. --clearsign or --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. --symmetric).
+
+@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. --list-config is
+only usable with --with-colons set.
+
+@end table
+
+
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************   FILES    ****************
+@c ***************            ****************
+@c *******************************************
+@c man begin FILES
+@node GPG Configuration
+@section Configuration files
+
+There are a few configuration files to control certain aspects of
+@command{gpg2}'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{gpg2} 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
+
+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.  For existing users the a small
+helper script is provided to create these files (@pxref{addgnupghome}).
+
+For internal purposes @command{gpg2} creates and maintaines a few other
+files; They all live in in the current home directory (@pxref{option
+--homedir}).  Only the @command{gpg2} may modify these files.
+
+@table @file
+@item pubring.gpg
+@cindex pubring.gpg
+xxx
+      
+@item random_seed
+@cindex random_seed
+xxxx
+
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  EXAMPLES  ****************
+@c ***************            ****************
+@c *******************************************
+@node GPG Examples
+@section Examples
+
+@c man begin EXAMPLES
+
+@example
+ fooo
+@end example
 
 @c man end
 
 @c man end
+
+
+
+
+ENDEND
+
+
+
+
+@c @chapheading How to specify a user ID
+
+There are different ways to specify a user ID to GnuPG; here are some
+examples:
+
+@table @asis
+
+@item 
+
+@item 234567C4
+@itemx 0F34E556E
+@itemx 01347A56A
+@itemx 0xAB123456
+Here the key ID is given in the usual short form.
+
+@item 234AABBCC34567C4
+@itemx 0F323456784E56EAB
+@itemx 01AB3FED1347A5612
+@itemx 0x234AABBCC34567C4
+Here the key ID is given in the long form as used by OpenPGP
+(you can get the long key ID using the option --with-colons).
+
+@item 1234343434343434C434343434343434
+@itemx 123434343434343C3434343434343734349A3434
+@itemx 0E12343434343434343434EAB3484343434343434
+@itemx 0xE12343434343434343434EAB3484343434343434
+The best way to specify a key ID is by using the fingerprint of
+the key. This avoids any ambiguities in case that there are duplicated
+key IDs (which are really rare for the long key IDs).
+
+@item =Heinrich Heine <heinrichh@@uni-duesseldorf.de>
+Using an exact to match string. The equal sign indicates this.
+
+@item <heinrichh@@uni-duesseldorf.de>
+Using the email address part which must match exactly. The left angle bracket
+indicates this email address mode.
+
+@item @@heinrichh
+Match within the <email.address> part of a user ID. The at sign
+indicates this email address mode.
+
+@item Heine
+@itemx *Heine
+By case insensitive substring matching. This is the default mode but
+applications may want to explicitly indicate this by putting the asterisk
+in front.
+@end table
+
+Note that you can append an exclamation mark (!) to key IDs or
+fingerprints. This flag tells GnuPG to use the specified primary or
+secondary key and not to try and calculate which primary or secondary
+key to use.
+@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.
+@chapheading 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 @chapheading ENVIRONMENT
+
+@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; only honored when
+--use-agent is set. 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 --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
+@chapheading FILES
+
+@table @asis
+
+@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 ~/.gnupg/gpg.conf
+Default configuration file
+
+@item ~/.gnupg/options
+Old style configuration file; only used when gpg.conf
+is not found
+
+@item /usr[/local]/share/gnupg/options.skel
+Skeleton options file
+
+@item /usr[/local]/lib/gnupg/
+Default location for extensions
+@end table
+
+@c @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.
+@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 --cipher-algo, --digest-algo,
+--cert-digest-algo, or --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 --pgp6, --pgp7, or --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.
+@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.
+
+
+
index 5a8778a..6a30a84 100644 (file)
@@ -37,15 +37,15 @@ Developer information:
 @section Commands
 
 Commands are not distinguished from options execpt for the fact that
 @section Commands
 
 Commands are not distinguished from options execpt for the fact that
-only one one command is allowed.
+only one command is allowed.
 
 @menu
 
 @menu
-* General Commands::        Commands not specific to the functionality.
-* Operational Commands::    Commands to select the type of operation.
-* Certificate Management::  How to manage certificates.
+* General GPGSM Commands::        Commands not specific to the functionality.
+* Operational GPGSM Commands::    Commands to select the type of operation.
+* Certificate Management::        How to manage certificates.
 @end menu
 
 @end menu
 
-@node General Commands
+@node General GPGSM Commands
 @subsection Commands not specific to the function
 
 @table @gnupgtabopt
 @subsection Commands not specific to the function
 
 @table @gnupgtabopt
@@ -67,7 +67,7 @@ abbreviate this command.
 
 
 
 
 
 
-@node Operational Commands
+@node Operational GPGSM Commands
 @subsection Commands to select the type of operation
 
 @table @gnupgtabopt
 @subsection Commands to select the type of operation
 
 @table @gnupgtabopt