Minor fixes.
[gnupg.git] / doc / gpgsm.texi
index 9df760c..ab2aae8 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 
@@ -223,21 +224,33 @@ checked right before it is used.
 
 @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
 Export all certificates stored in the Keybox or those specified by the
-optional @var{pattern}.  When using along with the @code{--armor} option
-a few informational lines are prepended before each block.
+optional @var{pattern}. Those pattern consist of a list of user ids
+(@pxref{how-to-specify-a-user-id}).  When used along with the
+@option{--armor} option a few informational lines are prepended before
+each block.  There is one limitation: As there is no commonly agreed
+upon way to pack more than one certificate into an ASN.1 structure, the
+binary export (i.e. without using @option{armor}) works only for the
+export of one certificate.  Thus it is required to specify a
+@var{pattern} which yields exactly one certificate.
 
 @item --export-secret-key-p12 @var{key-id}
 @opindex export
-Export the private key and the certificate identified by @var{key-id}
-in a PKCS#12 format. When using along with the @code{--armor} option
-a few informational lines are prepended to the output.  Note, that the
-PKCS#12 format is higly insecure and this command is only provided if
-there is no other way to exchange the private key.
+Export the private key and the certificate identified by @var{key-id} in
+a PKCS#12 format. When using along with the @code{--armor} option a few
+informational lines are prepended to the output.  Note, that the PKCS#12
+format is not very secure and this command is only provided if there is
+no other way to exchange the private key. (@pxref{option --p12-charset})
 
 @item --import [@var{files}]
 @opindex import
@@ -332,7 +345,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
@@ -397,7 +414,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
@@ -405,6 +422,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 *******************************************
@@ -437,6 +476,27 @@ Assume the input data is plain base-64 encoded.
 @opindex assume-binary
 Assume the input data is binary encoded.
 
+@anchor{option --p12-charset}
+@item --p12-charset @var{name}
+@opindex p12-charset
+@command{gpgsm} uses the UTF-8 encoding when encoding passphrases for
+PKCS#12 files.  This option may be used to force the passphrase to be
+encoded in the specified encoding @var{name}.  This is useful if the
+application used to import the key uses a different encoding and thus
+won't be able to import a file generated by @command{gpgsm}.  Commonly
+used values for @var{name} are @code{Latin1} and @code{CP850}.  Note
+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
@@ -518,11 +578,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
@@ -547,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
-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}
@@ -608,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.
 
+@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
@@ -673,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
-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
@@ -701,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.
 
+@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
@@ -710,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;
-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.
 
 
@@ -720,13 +820,22 @@ 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.
-      
+
 @item random_seed
 @cindex random_seed
 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
 
 
@@ -840,6 +949,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
 
 
@@ -1109,7 +1219,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}
@@ -1122,6 +1232,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