Minor fixes.
[gnupg.git] / doc / gpgsm.texi
index f9f7837..ab2aae8 100644 (file)
@@ -58,7 +58,7 @@ Developer information:
 @node GPGSM Commands
 @section Commands
 
 @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
 only one command is allowed.
 
 @menu
@@ -224,7 +224,13 @@ checked right before it is used.
 
 @item --delete-keys @var{pattern}
 @opindex delete-keys
 
 @item --delete-keys @var{pattern}
 @opindex delete-keys
-Delete the keys matching @var{pattern}.
+Delete the keys matching @var{pattern}.  Note that there is no command
+to delete the secret part of the key directly.  In case you need to do
+this, you should run the command @code{gpgsm --dump-secret-keys KEYID}
+before you delete the key, copy the string of hex-digits in the
+``keygrip'' line and delete the file consisting of these hex-digits
+and the suffix @code{.key} from the @file{private-keys-v1.d} directory
+below our GnuPG home directory (usually @file{~/.gnupg}).
 
 @item --export [@var{pattern}]
 @opindex export
 
 @item --export [@var{pattern}]
 @opindex export
@@ -342,6 +348,9 @@ to connect to this one.  Fallback to a pipe based server if this does
 not work.  Under Windows this option is ignored because the system dirmngr is
 always used.
 
 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
 Don't print a warning when the so called "secure memory" can't be used.
 @item --no-secmem-warning
 @opindex no-secmem-warning
 Don't print a warning when the so called "secure memory" can't be used.
@@ -569,6 +578,19 @@ encryption.  For convenience the strings @code{3DES}, @code{AES} and
 
 @table @gnupgtabopt
 
 
 @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
 @item --faked-system-time @var{epoch}
 @opindex faked-system-time
 This option is only useful for testing; it sets the system time back or
@@ -599,7 +621,7 @@ all of the debug messages you can get
 @end table
 
 How these messages are mapped to the actual debugging flags is not
 @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}
 however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
@@ -660,6 +682,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.
 
 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
 @end table
 
 All the long options may also be given in the configuration file after
@@ -725,13 +751,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
 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
 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
 in this file need to be listed also in @file{trustlist.txt}.
 
 This is a global file an installed in the data directory
@@ -753,6 +779,28 @@ 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.
 
 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.
+
+
+@item com-certs.pem
+@cindex com-certs.pem
+This file is a collection of common certificates used to populated a
+newly created @file{pubring.kbx}.  An administrator may replace this
+file with a custom one.  The format is a concatenation of PEM encoded
+X.509 certificates.  This global file is installed in the data directory
+(e.g. @file{/usr/share/gnupg/qualified.txt}).
+
 @end table
 
 @c man:.RE
 @end table
 
 @c man:.RE
@@ -762,7 +810,7 @@ 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 gpgsm creates and maintaines a few other files;
 helper script is provided to create these files (@pxref{addgnupghome}).
 
 For internal purposes gpgsm creates and maintaines a few other files;
-They all live in in the current home directory (@pxref{option
+they all live in in the current home directory (@pxref{option
 --homedir}).  Only @command{gpgsm} may modify these files.
 
 
 --homedir}).  Only @command{gpgsm} may modify these files.
 
 
@@ -772,7 +820,7 @@ They all live in in the current home directory (@pxref{option
 This a database file storing the certificates as well as meta
 information.  For debugging purposes the tool @command{kbxutil} may be
 used to show the internal structure of this file.
 This a database file storing the certificates as well as meta
 information.  For debugging purposes the tool @command{kbxutil} may be
 used to show the internal structure of this file.
-      
+
 @item random_seed
 @cindex random_seed
 This content of this file is used to maintain the internal state of the
 @item random_seed
 @cindex random_seed
 This content of this file is used to maintain the internal state of the
@@ -901,6 +949,7 @@ Assuan manual for details.
 * GPGSM EXPORT::          Export certificates.
 * GPGSM IMPORT::          Import certificates.
 * GPGSM DELETE::          Delete certificates.
 * GPGSM EXPORT::          Export certificates.
 * GPGSM IMPORT::          Import certificates.
 * GPGSM DELETE::          Delete certificates.
+* GPGSM GETINFO::         Information about the process
 @end menu
 
 
 @end menu
 
 
@@ -1170,7 +1219,7 @@ import private keys; a helper program is used for that.
 @node GPGSM DELETE
 @subsection Delete certificates
 
 @node GPGSM DELETE
 @subsection Delete certificates
 
-To delete certificate the command
+To delete certificate the command
 
 @example
   DELKEYS @var{pattern}
 
 @example
   DELKEYS @var{pattern}
@@ -1183,6 +1232,22 @@ this requires that the usual escape quoting rules are done.
 The certificates must be specified unambiguously otherwise an error is
 returned.
 
 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
 
 @mansect see also
 @ifset isman