doc: Fix recently introduced typo in gpgsm.texi.
[gnupg.git] / doc / gpg.texi
index 01dfeb7..ddebc69 100644 (file)
@@ -196,11 +196,13 @@ Make a detached signature.
 @item --encrypt
 @itemx -e
 @opindex encrypt
-Encrypt data. This command may be combined with @option{--sign} (to
-sign and encrypt a message), @option{--symmetric} (to encrypt a
-message that can decrypted using a secret key or a passphrase), or
-@option{--sign} and @option{--symmetric} together (for a signed
-message that can be decrypted using a secret key or a passphrase).
+Encrypt data to one or more public keys. This command may be combined
+with @option{--sign} (to sign and encrypt a message),
+@option{--symmetric} (to encrypt a message that can decrypted using a
+secret key or a passphrase), or @option{--sign} and
+@option{--symmetric} together (for a signed message that can be
+decrypted using a secret key or a passphrase).  @option{--recipient}
+and related options specify which public keys to use for encryption.
 
 @item --symmetric
 @itemx -c
@@ -309,43 +311,36 @@ the key using the command @option{--export-secret-subkeys}).  A
 @code{>} after these tags indicate that the key is stored on a
 smartcard.  See also @option{--list-keys}.
 
-@item --list-signatures
-@opindex list-signatures
-@itemx --list-sigs
-@opindex list-sigs
-Same as @option{--list-keys}, but the signatures are listed too.
-This command has the same effect as
-using @option{--list-keys} with @option{--with-sig-list}.
-
-For each signature listed, there are several flags in between the "sig"
-tag and keyid. These flags give additional information about each
-signature. From left to right, they are the numbers 1-3 for certificate
-check level (see @option{--ask-cert-level}), "L" for a local or
-non-exportable signature (see @option{--lsign-key}), "R" for a
-nonRevocable signature (see the @option{--edit-key} command "nrsign"),
-"P" for a signature that contains a policy URL (see
-@option{--cert-policy-url}), "N" for a signature that contains a
-notation (see @option{--cert-notation}), "X" for an eXpired signature
-(see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and
-above to indicate trust signature levels (see the @option{--edit-key}
-command "tsign").
-
 @item --check-signatures
 @opindex check-signatures
 @itemx --check-sigs
 @opindex check-sigs
-Same as @option{--list-signatures}, but the signatures are verified.  Note
-that for performance reasons the revocation status of a signing key is
-not shown.
-This command has the same effect as
+Same as @option{--list-keys}, but the key signatures are verified and
+listed too.  Note that for performance reasons the revocation status
+of a signing key is not shown.  This command has the same effect as
 using @option{--list-keys} with @option{--with-sig-check}.
 
-The status of the verification is indicated by a flag directly following
-the "sig" tag (and thus before the flags described above for
-@option{--list-signatures}).  A "!" indicates that the signature has been
-successfully verified, a "-" denotes a bad signature and a "%" is used
-if an error occurred while checking the signature (e.g. a non supported
-algorithm).
+The status of the verification is indicated by a flag directly
+following the "sig" tag (and thus before the flags described below.  A
+"!" indicates that the signature has been successfully verified, a "-"
+denotes a bad signature and a "%" is used if an error occurred while
+checking the signature (e.g. a non supported algorithm).  Signatures
+where the public key is not availabale are not listed; to see their
+keyids the command @option{--list-sigs} can be used.
+
+For each signature listed, there are several flags in between the
+signature status flag and keyid.  These flags give additional
+information about each key signature.  From left to right, they are
+the numbers 1-3 for certificate check level (see
+@option{--ask-cert-level}), "L" for a local or non-exportable
+signature (see @option{--lsign-key}), "R" for a nonRevocable signature
+(see the @option{--edit-key} command "nrsign"), "P" for a signature
+that contains a policy URL (see @option{--cert-policy-url}), "N" for a
+signature that contains a notation (see @option{--cert-notation}), "X"
+for an eXpired signature (see @option{--ask-cert-expire}), and the
+numbers 1-9 or "T" for 10 and above to indicate trust signature levels
+(see the @option{--edit-key} command "tsign").
+
 
 @item --locate-keys
 @opindex locate-keys
@@ -360,7 +355,7 @@ be used to locate a key.  Only public keys are listed.
 List all keys (or the specified ones) along with their
 fingerprints. This is the same output as @option{--list-keys} but with
 the additional output of a line with the fingerprint. May also be
-combined with @option{--list-signatures} or @option{--check-signatures}.  If this
+combined with @option{--check-signatures}.  If this
 command is given twice, the fingerprints of all secondary keys are
 listed too.  This command also forces pretty printing of fingerprints
 if the keyid format has been set to "none".
@@ -627,7 +622,9 @@ This section explains the main commands for key management.
 @table @gnupgtabopt
 
 @item --quick-generate-key @var{user-id} [@var{algo} [@var{usage} [@var{expire}]]]
+@itemx --quick-gen-key
 @opindex quick-generate-key
+@opindex quick-gen-key
 This is a simple command to generate a standard key with one user id.
 In contrast to @option{--generate-key} the key is generated directly
 without the need to answer a bunch of prompts.  Unless the option
@@ -1254,7 +1251,7 @@ Assume "no" on most questions.
 @opindex list-options
 This is a space or comma delimited string that gives options used when
 listing keys and signatures (that is, @option{--list-keys},
-@option{--list-signatures}, @option{--list-public-keys},
+@option{--check-signatures}, @option{--list-public-keys},
 @option{--list-secret-keys}, and the @option{--edit-key} functions).
 Options can be prepended with a @option{no-} (after the two dashes) to
 give the opposite meaning.  The options are:
@@ -1263,7 +1260,7 @@ give the opposite meaning.  The options are:
 
   @item show-photos
   @opindex list-options:show-photos
-  Causes @option{--list-keys}, @option{--list-signatures},
+  Causes @option{--list-keys}, @option{--check-signatures},
   @option{--list-public-keys}, and @option{--list-secret-keys} to
   display any photo IDs attached to the key.  Defaults to no. See also
   @option{--photo-viewer}.  Does not work with @option{--with-colons}:
@@ -1279,7 +1276,7 @@ give the opposite meaning.  The options are:
 
   @item show-policy-urls
   @opindex list-options:show-policy-urls
-  Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
+  Show policy URLs in the  @option{--check-signatures}
   listings.  Defaults to no.
 
   @item show-notations
@@ -1289,11 +1286,11 @@ give the opposite meaning.  The options are:
   @opindex list-options:show-std-notations
   @opindex list-options:show-user-notations
   Show all, IETF standard, or user-defined signature notations in the
-  @option{--list-signatures} or @option{--check-signatures} listings. Defaults to no.
+  @option{--check-signatures} listings. Defaults to no.
 
   @item show-keyserver-urls
   @opindex list-options:show-keyserver-urls
-  Show any preferred keyserver URL in the @option{--list-signatures} or
+  Show any preferred keyserver URL in the
   @option{--check-signatures} listings. Defaults to no.
 
   @item show-uid-validity
@@ -1316,7 +1313,7 @@ give the opposite meaning.  The options are:
 
   @item show-sig-expire
   @opindex list-options:show-sig-expire
-  Show signature expiration dates (if any) during @option{--list-signatures} or
+  Show signature expiration dates (if any) during
   @option{--check-signatures} listings. Defaults to no.
 
   @item show-sig-subpackets
@@ -1325,7 +1322,7 @@ give the opposite meaning.  The options are:
   optional argument list of the subpackets to list. If no argument is
   passed, list all subpackets. Defaults to no. This option is only
   meaningful when using @option{--with-colons} along with
-  @option{--list-signatures} or @option{--check-signatures}.
+  @option{--check-signatures}.
 
 @end table
 
@@ -1644,7 +1641,7 @@ Set what trust model GnuPG should follow. The models are:
   time a key is seen, it is memorized.  If later another key with a
   user id with the same email address is seen, both keys are marked as
   suspect.  In that case, the next time either is used, a warning is
-  displayed describing the conflict, why it might have occured
+  displayed describing the conflict, why it might have occurred
   (either the user generated a new key and failed to cross sign the
   old and new keys, the key is forgery, or a man-in-the-middle attack
   is being attempted), and the user is prompted to manually confirm
@@ -1726,14 +1723,18 @@ Set what trust model GnuPG should follow. The models are:
   exists.
 @end table
 
-@item --auto-key-locate @var{parameters}
+@item --auto-key-locate @var{mechanisms}
 @itemx --no-auto-key-locate
 @opindex 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
-mechanisms, in the order they are to be tried:
+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 mechanisms
+listed below, in the order they are to be tried.  Instead of listing
+the mechanisms as comma delimited arguments, the option may also be
+given several times to add more mechanism.  The option
+@option{--no-auto-key-locate} or the mechanism "clear" resets the
+list.  The default is "local,wkd".
 
 @table @asis
 
@@ -1749,7 +1750,6 @@ mechanisms, in the order they are to be tried:
 
   @item wkd
   Locate a key using the Web Key Directory protocol.
-  This is an experimental method and semantics may change.
 
   @item ldap
   Using DNS Service Discovery, check the domain in question for any LDAP
@@ -1782,13 +1782,14 @@ mechanisms, in the order they are to be tried:
 
 @end table
 
+
 @item --auto-key-retrieve
 @itemx --no-auto-key-retrieve
 @opindex auto-key-retrieve
 @opindex no-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.
+These options enable or disable the automatic retrieving of keys from
+a keyserver when verifying signatures made by keys that are not on the
+local keyring.  The default is @option{--no-auto-key-retrieve}.
 
 If the method "wkd" is included in the list of methods given to
 @option{auto-key-locate}, the signer's user ID is part of the
@@ -1972,6 +1973,9 @@ file name.
 Specify a dirmngr program to be used for keyserver access.  The
 default value is @file{@value{BINDIR}/dirmngr}.
 
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
+
 @item --no-autostart
 @opindex no-autostart
 Do not start the gpg-agent or the dirmngr if it has not yet been
@@ -2306,7 +2310,8 @@ opposite meaning. The options are:
   Show a listing of the key as imported right before it is stored.
   This can be combined with the option @option{--dry-run} to only look
   at keys; the option @option{show-only} is a shortcut for this
-  combination.
+  combination.  Note that suffixes like '#' for "sec" and "sbb" lines
+  may or may not be printed.
 
   @item import-export
   Run the entire import code but instead of storing the key to the
@@ -3079,8 +3084,9 @@ will be read from file descriptor @var{n}. If you use 0 for @var{n},
 the passphrase will be read from STDIN. This can only be used if only
 one passphrase is supplied.
 
-Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from GnuPG version 1.x.
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
 
 @item --passphrase-file @var{file}
 @opindex passphrase-file
@@ -3089,8 +3095,10 @@ be read from file @var{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.
-Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from GnuPG version 1.x.
+
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
 
 @item --passphrase @var{string}
 @opindex passphrase
@@ -3098,8 +3106,10 @@ Use @var{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.
-Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from GnuPG version 1.x.
+
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
 
 @item --pinentry-mode @var{mode}
 @opindex pinentry-mode
@@ -3217,6 +3227,16 @@ verification is not needed.
 Print key listings delimited by colons (like @option{--with-colons}) and
 print the public key data.
 
+@item --list-signatures
+@opindex list-signatures
+@itemx --list-sigs
+@opindex list-sigs
+Same as @option{--list-keys}, but the signatures are listed too.  This
+command has the same effect as using @option{--list-keys} with
+@option{--with-sig-list}.  Note that in contrast to
+@option{--check-signatures} the key signatures are not verified.
+
+
 @item --fast-list-mode
 @opindex fast-list-mode
 Changes the output of the list commands to work faster; this is achieved
@@ -3761,6 +3781,19 @@ 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.
 
+For scripted or other unattended use of @command{gpg} make sure to use
+the machine-parseable interface and not the default interface which is
+intended for direct use by humans.  The machine-parseable interface
+provides a stable and well documented API independent of the locale or
+future changes of @command{gpg}.  To enable this interface use the
+options @option{--with-colons} and @option{--status-fd}.  For certain
+operations the option @option{--command-fd} may come handy too.  See
+this man page and the file @file{DETAILS} for the specification of the
+interface.  Note that the GnuPG ``info'' pages as well as the PDF
+version of the GnuPG manual features a chapter on unattended use of
+GnuPG.  As an alternative the library @command{GPGME} can be used as a
+high-level abstraction on top of that interface.
+
 @mansect interoperability
 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS