Add some tests.
[gnupg.git] / doc / gpgsm.texi
index eed673c..3193e85 100644 (file)
@@ -58,7 +58,7 @@ Developer information:
 @node GPGSM Commands
 @section Commands
 
-Commands are not distinguished from options execpt for the fact that
+Commands are not distinguished from options except for the fact that
 only one command is allowed.
 
 @menu
@@ -164,8 +164,9 @@ use @samp{--help} to get a list of supported operations.
 @table @gnupgtabopt
 @item --gen-key
 @opindex gen-key
-This command will only print an error message and direct the user to the
-@command{gpgsm-gencert.sh} script.
+This command allows the interactive creation of a certifcate signing
+request.  It is commonly used along with the @option{--output} option to
+save the created CSR into a file.
 
 @item --list-keys
 @itemx -k 
@@ -338,7 +339,11 @@ a running dirmngr can't be connected.
 @opindex prefer-system-dirmngr
 If a system wide @command{dirmngr} is running in daemon mode, first try
 to connect to this one.  Fallback to a pipe based server if this does
-not work.
+not work.  Under Windows this option is ignored because the system dirmngr is
+always used.
+
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
 
 @item --no-secmem-warning
 @opindex no-secmem-warning
@@ -403,7 +408,7 @@ command.  This option should not be used in a configuration file.
 @itemx --disable-ocsp
 @opindex enable-ocsp
 @opindex disable-ocsp
-Be default @acronym{OCSP} checks are disabled.  The enable opton may
+Be default @acronym{OCSP} checks are disabled.  The enable option may
 be used to enable OCSP checks via Dirmngr.  If @acronym{CRL} checks
 are also enabled, CRLs will be used as a fallback if for some reason an
 OCSP request won't succeed.  Note, that you have to allow OCSP
@@ -411,6 +416,28 @@ requests in Dirmngr's configuration too (option
 @option{--allow-ocsp} and configure dirmngr properly.  If you don't do
 so you will get the error code @samp{Not supported}.
 
+@item --auto-issuer-key-retrieve
+@opindex auto-issuer-key-retrieve
+If a required certificate is missing while validating the chain of
+certificates, try to load that certificate from an external location.
+This usually means that Dirmngr is employed t search for the
+certificate.  Note that this option makes a "web bug" like behavior
+possible.  LDAP server 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 keybox), the operator can tell both your IP
+address and the time when you verified the signature.
+
+
+@item --validation-model @var{name}
+@opindex validation-model
+This option changes the default validation model.  The only possible
+values are "shell" (which is the default) and "chain" which forces the
+use of the chain model.  The chain model is also used if an option in
+the @file{trustlist.txt} or an attribute of the certificate requests it.
+However the standard model (shell) is in that case always tried first.
+
+
+
 @end table
 
 @c *******************************************
@@ -456,6 +483,14 @@ that @command{gpgsm} itself automagically imports any file with a
 passphrase encoded to the most commonly used encodings.
 
 
+@item --default-key @var{user_id}
+@opindex default-key
+Use @var{user_id} as the standard key for signing.  This key is used if
+no other key has been defined as a signing key.  Note, that the first
+@option{--local-users} option also sets this key if it has not yet been
+set; however @option{--default-key} always overrides this.
+
+
 @item --local-user @var{user_id}
 @item -u @var{user_id}
 @opindex local-user
@@ -537,11 +572,25 @@ encryption.  For convenience the strings @code{3DES}, @code{AES} and
 
 @table @gnupgtabopt
 
+@item --extra-digest-algo @var{name}
+@opindex extra-digest-algo
+Sometimes signatures are broken in that they announce a different digest
+algorithm than actually used.  @command{gpgsm} uses a one-pass data
+processing model and thus needs to rely on the announcde digest
+algorithms to properly hash the data.  As a workaround this option may
+be used to tell gpg to also hash the data using the algorithm
+@var{name}; this slows processing down a little bit but allows to verify
+such broken signatures.  If @command{gpgsm} prints an error like
+``digest algo 8 has not been enabled'' you may want to try this option,
+with @samp{SHA256} for @var{name}.
+
+
 @item --faked-system-time @var{epoch}
 @opindex faked-system-time
 This option is only useful for testing; it sets the system time back or
 forth to @var{epoch} which is the number of seconds elapsed since the year
-1970.
+1970.  Alternativly @var{epoch} may be given as a full ISO time string
+(e.g. "20070924T154812").
 
 @item --with-ephemeral-keys
 @opindex with-ephemeral-keys
@@ -566,7 +615,7 @@ all of the debug messages you can get
 @end table
 
 How these messages are mapped to the actual debugging flags is not
-specified and may change with newer releaes of this program. They are
+specified and may change with newer releases of this program. They are
 however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
@@ -627,6 +676,10 @@ Supply the passphrase @var{string} to the gpg-protect-tool.  This
 option is only useful for the regression tests included with this
 package and may be revised or removed at any time without notice.
 
+@item --no-common-certs-import
+@opindex no-common-certs-import
+Suppress the import of common certificates on keybox creation.
+
 @end table
 
 All the long options may also be given in the configuration file after
@@ -692,13 +745,13 @@ signatures in the same way as handwritten signatures are.  Comments
 start with a hash mark and empty lines are ignored.  Lines do have a
 length limit but this is not a serious limitation as the format of the
 entries is fixed and checked by gpgsm: A non-comment line starts with
-optional white spaces, followed by exactly 40 hex character, white space
+optional whitespace, followed by exactly 40 hex character, white space
 and a lowercased 2 letter country code.  Additional data delimited with
 by a white space is current ignored but might late be used for other
 purposes.
 
 Note that even if a certificate is listed in this file, this does not
-mean that thecertificate is trusted; in general the certificates listed
+mean that the certificate is trusted; in general the certificates listed
 in this file need to be listed also in @file{trustlist.txt}.
 
 This is a global file an installed in the data directory
@@ -720,6 +773,20 @@ confirm that such a legally binding signature shall really be created.
 Because this software has not yet been approved for use with such
 certificates, appropriate notices will be shown to indicate this fact.
 
+@item help.txt
+@cindex help.txt
+This is plain text file with a few help entries used with 
+@command{pinentry} as well as a large list of help items for
+@command{gpg} and @command{gpgsm}.  The standard file has English help
+texts; to install localized versions use filenames like @file{help.LL.txt}
+with LL denoting the locale.  GnuPG comes with a set of predefined help
+files in the data directory (e.g. @file{/usr/share/gnupg/help.de.txt})
+and allows overriding of any help item by help files stored in the
+system configuration directory (e.g. @file{/etc/gnupg/help.de.txt}).
+For a reference of the help file's syntax, please see the installed
+@file{help.txt} file.
+
+
 @end table
 
 @c man:.RE
@@ -746,6 +813,15 @@ This content of this file is used to maintain the internal state of the
 random number generator accross invocations.  The same file is used by
 other programs of this software too.
 
+@item S.gpg-agent
+@cindex S.gpg-agent
+If this file exists and the environment variable @env{GPG_AGENT_INFO} is
+not set, @command{gpgsm} will first try to connect to this socket for
+accessing @command{gpg-agent} before starting a new @command{gpg-agent}
+instance.  Under Windows this socket (which in reality be a plain file
+describing a regular TCP litening port) is the standard way of
+connecting the @command{gpg-agent}.
+
 @end table
 
 
@@ -859,6 +935,7 @@ Assuan manual for details.
 * GPGSM EXPORT::          Export certificates.
 * GPGSM IMPORT::          Import certificates.
 * GPGSM DELETE::          Delete certificates.
+* GPGSM GETINFO::         Information about the process
 @end menu
 
 
@@ -1128,7 +1205,7 @@ import private keys; a helper program is used for that.
 @node GPGSM DELETE
 @subsection Delete certificates
 
-To delete certificate the command
+To delete certificate the command
 
 @example
   DELKEYS @var{pattern}
@@ -1141,6 +1218,22 @@ this requires that the usual escape quoting rules are done.
 The certificates must be specified unambiguously otherwise an error is
 returned.
 
+@node GPGSM GETINFO
+@subsection  Return information about the process
+
+This is a multipurpose function to return a variety of information.
+
+@example
+GETINFO @var{what}
+@end example
+
+The value of @var{what} specifies the kind of information returned:
+@table @code
+@item version
+Return the version of the program.
+@item pid
+Return the process id of the process.
+@end table
 
 @mansect see also
 @ifset isman